TypeScript requests

Every operation takes one argument object. The object has up to five keys, and TypeScript requires only the ones the operation actually uses.

Key	Contains
`path`	Path parameters, such as `event_id` or `issue_id`.
`query`	Query parameters, such as `limit`, `after`, and `status`.
`headers`	Request headers, such as `Idempotency-Key`.
`body`	The JSON request body.
`request`	Cancellation, timeout, and retry controls for this call.

Operations with no required input accept no argument at all.

const info = await client.metadata.getApiInfo();

const events = await client.events.listEvents({
  query: { limit: 25 },
});

const issue = await client.issues.getIssue({
  path: { issue_id: "00000000-0000-7000-8000-000000000001" },
});

Path and body together

An operation with both takes them as separate keys of one object:

const issue = await client.issues.updateIssue({
  path: { issue_id: "00000000-0000-7000-8000-000000000001" },
  body: { assigned_to: "00000000-0000-7000-8000-000000000002" },
});

Assignment is repeatable. Send the same request again to get the same result.

Headers

Idempotency-Key is the only optional header on the public contract, and it applies only to note creation.

const note = await client.issues.addIssueNote({
  path: { issue_id: "00000000-0000-7000-8000-000000000001" },
  headers: { "Idempotency-Key": "note-provider-late-000000000001" },
  body: { body: "Confirmed that the provider callback arrived late." },
});

Reuse the same key with the same body to retry safely. Reusing the key with a different body returns 409.

Per-request controls

The request key overrides the client defaults for one call:

const controller = new AbortController();

const events = await client.events.listEvents({
  query: { limit: 100 },
  request: {
    signal: controller.signal,
    timeoutMs: 10_000,
    retry: { maxAttempts: 2 },
  },
});

timeoutMs defaults to the client timeout of 30 seconds. Set it to 0 to disable the timeout for one call. Aborting through signal rejects with the signal’s reason and does not retry.

Custom fetch

Pass your own fetch for tests, proxies, or instrumentation.

const client = new ReconifyClient({
  apiKey: process.env.RECONIFY_API_KEY,
  fetch: async (input, init) => {
    const started = Date.now();
    const response = await fetch(input, init);
    metrics.observe("reconify_request_ms", Date.now() - started);
    return response;
  },
});

You can also set headers on the client to add a header to every request, such as a service name for your own tracing.

Types

The SDK derives its types from the contract, so you can name the exact input or output of any operation without importing a hand-written interface.

import type { RequestParams, ResponseBody } from "@reconifyhq/sdk";

const params: RequestParams<"list-events"> = {
  query: { limit: 25 },
};

const page: ResponseBody<"list-events"> = await client.events.listEvents(params);

Named model types are also exported for the shapes you pass around your own code.

import type { Event, Issue, MonitoringBatchRequest, MonitoringResult, Note } from "@reconifyhq/sdk";

function buildBatch(orders: Order[]): MonitoringBatchRequest {
  return {
    events: orders.map((order) => ({
      id: order.eventId,
      flow: "payment_to_wallet",
      type: "payment.succeeded",
      occurred_at: order.paidAt.toISOString(),
      amount: order.amount.toFixed(2),
      currency: order.currency,
      reference: order.id,
      entity_id: order.walletId,
    })),
  };
}

Import from the package entrypoint only. Internal paths such as @reconifyhq/sdk/dist/core/transport.js are not part of the supported interface and can change in a patch release.

Read collections page by page in Pagination.

Overview

TypeScript

Python

Path and body together

Headers

Per-request controls

Custom fetch

Types

Next

​Path and body together

​Headers

​Per-request controls

​Custom fetch

​Types

​Next

Path and body together

Headers

Per-request controls

Custom fetch

Types

Next