The client your agent calls

new AdeiaClient(options: AdeiaClientOptions): AdeiaClient

apiKey required

The key npm run seed printed once. Sent as authorization: Bearer <key> on every request.

baseUrl http://localhost:3000

Where the layer is listening. Trailing slashes are trimmed, so a URL out of an env file does not produce a double slash.

fetch global fetch

Injectable purely so tests need no live server. Anything matching the fetch signature will do.

Throws

A plain Error — AdeiaClient requires an apiKey — when the key is empty. Construction is synchronous and sends nothing; the first request happens when you call a method.

requestAction(req: ActionRequestInput): Promise<ActionRecord>

Returns

The decided record. Executed, held for a person, or refused — the promise resolves either way, so read status rather than assuming success.

Throws

AdeiaError on any non-2xx response: invalid_request (400, carrying issues), unauthorized (401), internal_error (500). A policy denial is none of these.

await adeia.requestAction({
  type: "payment",
  idempotencyKey: `invoice-${invoice.id}`,   // optional
  params: {
    amountCents: 50000,                    // integer, positive
    currency: "usd",                       // three lowercase letters
    recipient: "acct_contractor",
    description: "Q3 design work",         // optional, ≤ 500 chars
  },
});

Omit idempotencyKey and the client generates a fresh UUID for that call. Supply your own when a retry should be recognised as the same logical action — a new key is a new payment. The body is validated strictly, so a misspelled field is a 400 you can see rather than a key that vanishes.

There is no automatic retry, deliberately. A blind retry against a payment endpoint is how double charges happen. The idempotency key makes a retry safe; the decision to make one stays with you.

getAction(id: string): Promise<ActionRecord>

Returns

The record as it stands right now. The id is URL-encoded for you.

Throws

AdeiaError with status: 404 and code: "not_found" for an id that does not exist — and for another project's action, which is deliberately the same answer. A 403 there would confirm the id exists.

waitForAction(id: string, opts?: WaitOptions): Promise<ActionRecord>

timeoutMs 300000

Five minutes. Long enough for someone to read an approval email and click through, short enough that an ignored request does not hang an agent forever.

pollMs 2000

How long it sleeps between reads.

Returns

The record once it reaches a terminal status. It reads once before it starts waiting, so an action that has already finished comes back without a sleep.

Throws

AdeiaTimeoutError when the deadline passes while the action is still in flight. That is not a failed action — a human may simply not have decided yet, and the id is still good. Any AdeiaError from the underlying read passes straight through.

class AdeiaError extends Error {
  name: "AdeiaError";
  status: number;
  code: string;
  issues?: unknown[];
}

status

The HTTP status of the response.

code

The server's machine-readable code — one of unauthorized, not_found, invalid_request, internal_error — so you can branch without parsing prose. It falls back to unknown_error when a response carried none.

issues optional

The validation issue list, present only when the server sent one. This is where a bad amount or a missing recipient shows up.

import { AdeiaError } from "@adeia/sdk";

try {
  await adeia.requestAction(req);
} catch (err) {
  if (err instanceof AdeiaError && err.code === "invalid_request") {
    console.error(err.issues);
  }
}

The message reads POST /v1/actions failed with 400. The detail is on the properties, not in the prose.

class AdeiaTimeoutError extends Error {
  name: "AdeiaTimeoutError";
  actionId: string;
  lastStatus: string;
}

Thrown by

waitForAction, and nothing else.

Carries

actionId and lastStatus, so you can report what it was still doing, or come back and poll the same id later.

It extends Error directly, not AdeiaError. A check for err instanceof AdeiaError is false for a timeout — branch on it by name.