@relume_io/partner-node 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,503 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+type CallType = 'user.get' | 'credits.get' | 'credits.charge' | 'credits.reverse';
+/** Passed to every callback, for your logs. */
+interface CallContext {
+    type: CallType;
+    /** Relume-Request-Id: unique per attempt. Quote it to Relume support. */
+    requestId: string | null;
+}
+/** What `onGetUser` returns. Every field is optional; null or '' counts as unset. */
+interface UserProfile {
+    /** At most 200 characters. */
+    name?: string | null;
+    /** A valid email address. */
+    email?: string | null;
+    /** An https URL. */
+    avatarUrl?: string | null;
+}
+interface Credits {
+    /** The user's balance in your own credits (the unit of partnerCredits). Whole number, zero or more. */
+    balance: number;
+}
+interface Charge {
+    /** Your own id for the user. */
+    userId: string;
+    /**
+     * Idempotency key. Debit at most once per chargeId, and answer a repeat
+     * with the same result as the first time.
+     */
+    chargeId: string;
+    /** What to debit from the user's wallet. At least 1. */
+    partnerCredits: number;
+    /**
+     * What Relume charges you for this action, for your records only.
+     * Never debit it from the wallet.
+     */
+    relumeCredits: number;
+    /** The billable action, e.g. `page.unlock`. New actions may appear. */
+    action: string;
+    siteId?: string;
+    pageId?: string;
+    /** For the user's wallet statement. At most 200 characters. */
+    description: string;
+}
+interface ChargeResult {
+    /** True if the wallet was debited; false if the user can't afford it (sent as 402). */
+    ok: boolean;
+    /** The balance after the charge. Saves Relume a credits.get call. */
+    balance?: number | null;
+}
+/** `work_failed`, `charge_unknown` or `staff_refund`. New reasons may appear. */
+type ReversalReason = 'work_failed' | 'charge_unknown' | 'staff_refund' | (string & {});
+interface Reversal {
+    userId: string;
+    /** Idempotency key. Credit at most once per reversalId. */
+    reversalId: string;
+    /** What to credit back to the wallet. At least 1. */
+    partnerCredits: number;
+    /** The relumeCredits being given back, for your records only. Never credit it to the wallet. */
+    relumeCredits: number;
+    /**
+     * The charge being reversed. Absent for a staff refund. If you never debited
+     * this charge (it timed out before reaching your wallet), credit nothing,
+     * and record it as declined: if the charge itself arrives later, it must
+     * not debit.
+     */
+    chargeId?: string;
+    reason: ReversalReason;
+}
+interface ReversalResult {
+    balance?: number | null;
+}
+type MaybePromise<T> = T | Promise<T>;
+/** Return null when you don't know the user: Relume refuses the session. */
+type GetUserCallback = (userId: string, context: CallContext) => MaybePromise<UserProfile | null | undefined>;
+type GetCreditsCallback = (userId: string, context: CallContext) => MaybePromise<Credits>;
+type ChargeCreditsCallback = (charge: Charge, context: CallContext) => MaybePromise<ChargeResult>;
+type ReverseChargeCallback = (reversal: Reversal, context: CallContext) => MaybePromise<ReversalResult | void>;
+/**
+ * Who is signed in, from the browser's GET /relume/session request: the
+ * Express/Node request for `relume.express()`, the `Request` for
+ * `relume.fetchHandler`. Return null when nobody is signed in. Never read the
+ * user id from the query string or body.
+ */
+type GetUserIdFromRequest<TRequest> = (request: TRequest) => MaybePromise<string | number | null | undefined>;
+/** A response from the framework-agnostic handlers, always JSON. */
+interface RelumeResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+}
+/** Where the handlers report errors your callbacks threw or returned. */
+interface HandlerErrorInfo {
+    route: 'session' | 'calls';
+    type?: CallType;
+    requestId?: string | null;
+}
+
+/** An Express request, or a plain node:http one. */
+type NodeRequest = IncomingMessage & {
+    body?: unknown;
+    /** Set by Express to the mount path, e.g. '/relume'. */
+    baseUrl?: string;
+};
+type NodeHandler = (request: NodeRequest, response: ServerResponse, next?: (error?: unknown) => void) => void;
+
+/** Every `error.code` the partner API sends (protocol section 9). */
+type PartnerApiErrorCode = 'invalid_request' | 'invalid_cursor' | 'missing_api_key' | 'invalid_api_key' | 'partner_suspended' | 'user_deactivated' | 'user_suspended' | 'not_found' | 'user_not_found' | 'site_not_found' | 'export_not_found' | 'ledger_entry_not_found' | 'partner_user_unknown' | 'rate_limited' | 'internal_error' | 'not_implemented' | 'partner_endpoint_error';
+/** One page of a list endpoint. */
+interface Page<T> {
+    data: T[];
+    /** Always present. Pass it as `after` to continue. */
+    nextCursor: string;
+    hasMore: boolean;
+}
+/** `?after=&limit=` on every list endpoint. */
+interface PageQuery {
+    /** A `nextCursor` from the same list. Omit to start from the beginning. */
+    after?: string;
+    /** 1 to 100. Default 50. */
+    limit?: number;
+}
+interface CreateSessionBody {
+    /** Your own id for the user, 1 to 128 characters. */
+    userId: string;
+}
+interface Session {
+    /** Single use, valid for 5 minutes, bound to this environment's publishable key. */
+    clientSecret: string;
+    expiresAt: string;
+}
+type UserStatus = 'active' | 'deactivated' | 'suspended';
+interface User {
+    userId: string;
+    /** `suspended` users can only be reactivated by Relume staff. */
+    status: UserStatus;
+    createdAt: string;
+    /** When the user last opened the builder; null before their first session. */
+    lastActiveAt: string | null;
+    /** Sites they own, deleted sites excluded. */
+    siteCount: number;
+}
+/** New statuses only come with notice (protocol section 12). */
+type ExportStatus = 'queued' | 'running' | 'ready' | 'failed' | 'expired';
+interface Export {
+    exportId: string;
+    siteId: string;
+    status: ExportStatus;
+    /** A signed zip URL; null unless `status` is `ready`. */
+    downloadUrl: string | null;
+    createdAt: string;
+    /** When `downloadUrl` stops working; null unless `status` is `ready`. */
+    expiresAt: string | null;
+}
+interface Site {
+    /** The id `relume.open({ site })` takes. */
+    siteId: string;
+    /** Your own id for the owner. */
+    userId: string;
+    name: string;
+    createdAt: string;
+    /** Includes changes Relume makes itself, such as a new screenshot. */
+    updatedAt: string;
+    /** Signed, and stops working within 7 days: fetch the site again rather than store it. */
+    thumbnailUrl: string | null;
+    /** The most recent export. Always null until exports ship. */
+    lastExport: Export | null;
+}
+interface CreateSiteBody {
+    /** At most 200 characters. Default "Untitled site". */
+    name?: string;
+}
+interface CreatedSite {
+    siteId: string;
+}
+type LedgerEntryType = 'charge' | 'reversal';
+/**
+ * A charge is `pending`, `charged`, `declined`, `unknown`, `void` or
+ * `reversed`; a reversal is `pending` or `reversed`. New statuses only come
+ * with notice (protocol section 12).
+ */
+type LedgerEntryStatus = 'pending' | 'charged' | 'declined' | 'unknown' | 'void' | 'reversed';
+interface LedgerEntry {
+    /** The `chargeId` or `reversalId` sent in the call: upsert on it. */
+    id: string;
+    type: LedgerEntryType;
+    status: LedgerEntryStatus;
+    userId: string;
+    partnerCredits: number;
+    relumeCredits: number;
+    /** Null when it doesn't apply, e.g. on a staff refund. New actions may appear. */
+    action: string | null;
+    siteId: string | null;
+    pageId: string | null;
+    /** On a reversal tied to a charge; otherwise null. */
+    chargeId: string | null;
+    /** On a reversal (`work_failed`, `charge_unknown`, `staff_refund`, …); otherwise null. */
+    reason: string | null;
+    createdAt: string;
+    /** When the entry reached a final status; otherwise null. */
+    resolvedAt: string | null;
+}
+interface PartnerResponse {
+    /** From the last attempt; null after a timeout or network error. */
+    httpStatus: number | null;
+    body: {
+        balance: number;
+    } | Record<string, never> | null;
+    attempts: number;
+}
+/** `GET /ledger/{id}` adds what your endpoint last answered. */
+interface LedgerEntryDetail extends LedgerEntry {
+    /** Null when Relume resolved the entry without calling you. */
+    partnerResponse: PartnerResponse | null;
+}
+type UsageGroup = 'day' | 'user' | 'action';
+/** The query string of `GET /usage`, as sent. */
+interface UsageQuery extends PageQuery {
+    /** `YYYY-MM-DD` (UTC), inclusive. */
+    from: string;
+    /** `YYYY-MM-DD` (UTC), exclusive. At most 366 days after `from`. */
+    to: string;
+    /** Comma-separated subset of `day`, `user`, `action`. */
+    groupBy?: string;
+}
+interface UsageTotals {
+    charged: number;
+    reversed: number;
+    /** `charged - reversed`. Relume invoices on `relumeCredits.net`. */
+    net: number;
+}
+interface UsageRow {
+    /** `YYYY-MM-DD`; only when grouped by day. */
+    day?: string;
+    /** Only when grouped by user. */
+    userId?: string;
+    /** Only when grouped by action; null for a staff refund. */
+    action?: string | null;
+    partnerCredits: UsageTotals;
+    relumeCredits: UsageTotals;
+}
+interface Price {
+    action: string;
+    /** Null until Relume staff set one; Relume refuses the action until then. */
+    partnerCredits: number | null;
+    relumeCredits: number;
+}
+
+declare const DEFAULT_API_BASE_URL = "https://apis.relume.io/nova/partner/v1";
+/**
+ * A partner API `error.code`, or one the SDK sets itself: `timeout` and
+ * `network_error` when no response arrived, `unexpected_response` when one
+ * arrived without the expected body. New API codes may appear.
+ */
+type RelumeErrorCode = PartnerApiErrorCode | 'timeout' | 'network_error' | 'unexpected_response' | (string & {});
+/** An error answer from the partner API, or a request that never got one. */
+declare class RelumeError extends Error {
+    /** The HTTP status, or 0 when no response arrived. */
+    readonly status: number;
+    /** The API's `error.code`, safe to switch on. */
+    readonly code: RelumeErrorCode;
+    readonly requestId: string | null;
+    constructor(input: {
+        status: number;
+        code: RelumeErrorCode;
+        message: string;
+        requestId?: string | null;
+        cause?: unknown;
+    });
+}
+
+/**
+ * A list endpoint, fetched a page at a time as you iterate:
+ *
+ *     for await (const entry of relume.ledger.list({ after })) { … }
+ *
+ * Nothing is requested until iteration starts, and each iteration starts
+ * again from the `after` the list was made with. Iterate `pages()` instead to
+ * handle (and checkpoint) a page at a time. Iterate a list once at a time:
+ * every iteration moves the same `nextCursor`, so two at once would leave it
+ * wherever the last one got to.
+ */
+declare class PagedList<T> implements AsyncIterable<T> {
+    #private;
+    constructor(fetchPage: (after: string | undefined) => Promise<Page<T>>, after: string | undefined);
+    /**
+     * Where to resume: the `nextCursor` of the last page whose items have all
+     * been handed out, or the starting `after` (null when there was none)
+     * before that. Once iteration ends, store it and pass it as `after` later
+     * to get only what is new (on the ledger; site cursors don't poll).
+     */
+    get nextCursor(): string | null;
+    /** Every page in turn. The cursor advances when you ask for the next one. */
+    pages(): AsyncGenerator<Page<T>, void, undefined>;
+    [Symbol.asyncIterator](): AsyncGenerator<T, void, undefined>;
+    /** Every item in one array. Mind the size of what you're listing. */
+    toArray(): Promise<T[]>;
+}
+
+interface UsageParams extends Omit<UsageQuery, 'groupBy'> {
+    /** One row per combination of these. Omitted: one row for the whole range. */
+    groupBy?: readonly UsageGroup[];
+}
+interface PartnerApi {
+    sessions: {
+        /**
+         * POST /sessions: a single-use client secret for this user's embed. The
+         * first call for a userId creates their Relume account with user.get.
+         */
+        create(input: CreateSessionBody): Promise<Session>;
+    };
+    users: {
+        /** GET /users/{userId}. `user_not_found` until their first session. */
+        get(userId: string): Promise<User>;
+        /**
+         * POST /users/{userId}/deactivate: cuts off their sessions and export
+         * links; data is kept. Idempotent, and retried on a 5xx.
+         */
+        deactivate(userId: string): Promise<User>;
+        /** POST /users/{userId}/reactivate. `user_suspended` if Relume staff suspended them. */
+        reactivate(userId: string): Promise<User>;
+    };
+    sites: {
+        /**
+         * GET /users/{userId}/sites, most recently updated first. Fetch from the
+         * beginning each time: new and changed sites sort to the front, so a
+         * stored cursor never shows them.
+         */
+        list(userId: string, params?: PageQuery): PagedList<Site>;
+        /** POST /users/{userId}/sites: an empty site. Not idempotent, so a 5xx isn't retried. */
+        create(userId: string, input?: CreateSiteBody): Promise<CreatedSite>;
+        /** GET /sites/{siteId}. */
+        get(siteId: string): Promise<Site>;
+    };
+    exports: {
+        /**
+         * GET /sites/{siteId}/exports/{exportId}. Not available yet: answers
+         * `not_implemented` (501) until exports ship.
+         */
+        get(siteId: string, exportId: string): Promise<Export>;
+    };
+    ledger: {
+        /**
+         * GET /ledger, in change order: an entry appears again each time its
+         * status changes, so upsert on `id`. Store the list's `nextCursor` when
+         * you're done and pass it as `after` to get only what changed since.
+         */
+        list(params?: PageQuery): PagedList<LedgerEntry>;
+        /** GET /ledger/{id}: one entry by chargeId or reversalId, with partnerResponse. */
+        get(id: string): Promise<LedgerEntryDetail>;
+    };
+    usage: {
+        /** GET /usage: credits totalled over [from, to), ordered by day, user, action. */
+        get(params: UsageParams): PagedList<UsageRow>;
+    };
+    prices: {
+        /** GET /prices: every billable action's price in this environment. */
+        list(): Promise<Price[]>;
+    };
+}
+
+interface RelumeOptions {
+    /** `sk_test_…` or `sk_live_…`. Server only: never send it to a browser. */
+    secretKey: string;
+    /** Defaults to production. Relume gives you another URL for staging. */
+    apiBaseUrl?: string;
+    /** Per partner API request attempt. Default 15 seconds. */
+    apiTimeoutMs?: number;
+    /**
+     * Retries after the first attempt. Default 2. A 429 is retried after its
+     * Retry-After; a 5xx or a failed connection with backoff, except on
+     * `sites.create`, which isn't idempotent. 0 turns retries off.
+     */
+    maxRetries?: number;
+    /** Replace `fetch` for partner API requests, e.g. to add a proxy agent. */
+    fetch?: typeof fetch;
+    /**
+     * Called when a callback throws or returns something the protocol doesn't
+     * allow, or the session route fails. Defaults to console.error. The caller
+     * always gets a 5xx; Relume never sees the error's message.
+     */
+    onHandlerError?: (error: unknown, info: HandlerErrorInfo) => void;
+    /** The clock, in milliseconds. For tests. */
+    now?: () => number;
+    /** Waits between retries. For tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * A Relume partner client. Create one with `Relume.init`; there is no global
+ * state, so test and live clients can sit side by side.
+ *
+ * `TRequest` is the request your `getUserIdFromRequest` receives: the
+ * Express/Node request for `express()`, the `Request` for `fetchHandler`.
+ */
+declare class Relume<TRequest = unknown> {
+    #private;
+    readonly sessions: PartnerApi['sessions'];
+    readonly users: PartnerApi['users'];
+    readonly sites: PartnerApi['sites'];
+    readonly exports: PartnerApi['exports'];
+    readonly ledger: PartnerApi['ledger'];
+    readonly usage: PartnerApi['usage'];
+    readonly prices: PartnerApi['prices'];
+    /**
+     * A fetch-style handler for Next.js route handlers, Hono, Cloudflare
+     * Workers, Bun and Deno. Answers `GET …/session` and `POST …/calls`.
+     */
+    readonly fetchHandler: (request: Request) => Promise<Response>;
+    static init<TRequest = unknown>(options: RelumeOptions): Relume<TRequest>;
+    constructor(options: RelumeOptions);
+    /** Who is signed in, for the browser's `GET /relume/session`. */
+    getUserIdFromRequest(callback: GetUserIdFromRequest<TRequest>): this;
+    /** Answers `user.get`: the user's profile, or null if you don't know them. */
+    onGetUser(callback: GetUserCallback): this;
+    /** Answers `credits.get`: `{ balance }` in your own credits. */
+    onGetCredits(callback: GetCreditsCallback): this;
+    /**
+     * Answers `credits.charge`. Debit `partnerCredits` (never `relumeCredits`),
+     * at most once per `chargeId`, and return `{ ok, balance }`.
+     */
+    onChargeCredits(callback: ChargeCreditsCallback): this;
+    /**
+     * Answers `credits.reverse`. Credit back `partnerCredits` (never
+     * `relumeCredits`), at most once per `reversalId`. If `chargeId` names a
+     * debit you never made, change nothing and return normally.
+     */
+    onReverseCharge(callback: ReverseChargeCallback): this;
+    /**
+     * Express (or Connect, or plain `node:http`) middleware. Mount it before
+     * any body parser: `app.use('/relume', relume.express())`.
+     */
+    express(): NodeHandler;
+    /**
+     * `POST /relume/calls`, framework-agnostic: verifies the signature and the
+     * 5-minute window, routes by `type`, runs your callback and validates what
+     * it returns. Pass the raw body exactly as received.
+     */
+    handleCall(input: {
+        rawBody: string | Uint8Array;
+        signatureHeader: string | null | undefined;
+        requestId?: string | null;
+    }): Promise<RelumeResponse>;
+    /**
+     * `GET /relume/session`, framework-agnostic: works out the signed-in user
+     * with `getUserIdFromRequest`, calls `POST /sessions` and returns the
+     * client secret, or passes the API's error through unchanged.
+     */
+    handleSession(request: TRequest): Promise<RelumeResponse>;
+}
+
+/** Thrown when a callback returns something the protocol doesn't allow. */
+declare class InvalidCallbackResultError extends Error {
+    constructor(message: string);
+}
+
+declare const SIGNATURE_HEADER = "Relume-Signature";
+declare const REQUEST_ID_HEADER = "Relume-Request-Id";
+/** How far a call's timestamp may be from this server's clock, either way. */
+declare const SIGNATURE_TOLERANCE_SECONDS: number;
+/** The current key plus the previous one during a rotation overlap. */
+declare const MAX_SIGNATURES = 2;
+type SignatureFailure = 'malformed_header' | 'signature_mismatch' | 'timestamp_out_of_tolerance';
+type VerifySignatureResult = {
+    valid: true;
+    timestamp: number;
+} | {
+    valid: false;
+    reason: SignatureFailure;
+};
+interface ParsedSignatureHeader {
+    timestamp: number;
+    /** Every v1= value in header order, including ones that aren't hex. */
+    signatures: string[];
+}
+/** Lowercase hex HMAC-SHA256 of `t + "." + rawBody`, keyed by the secret key. */
+declare function computeSignature(secret: string, timestamp: number, rawBody: string | Uint8Array): Promise<string>;
+/**
+ * Builds a Relume-Signature header the way Relume does: newest secret first,
+ * a second one only during a rotation. For a partner's own tests; a partner's
+ * server never needs to sign anything.
+ */
+declare function signCall(secrets: string | readonly string[], timestamp: number, rawBody: string | Uint8Array): Promise<string>;
+/**
+ * Null when the header has no `t`, more than one `t`, a `t` that isn't
+ * canonical unix seconds, no v1= value, or more than two v1= values. Entries
+ * with another name (a future `v2=`) are ignored.
+ */
+declare function parseSignatureHeader(header: string): ParsedSignatureHeader | null;
+/**
+ * Verifies a call: the header parses, any v1= value matches the HMAC under
+ * `secret` (compared in constant time by Web Crypto), and `t` is within 300
+ * seconds of `nowSeconds`. The signature is checked before the timestamp, so
+ * a stale result is only reported for a call Relume really signed.
+ */
+declare function verifySignature(input: {
+    secret: string;
+    header: string | null | undefined;
+    rawBody: string | Uint8Array;
+    /** Defaults to the current time. */
+    nowSeconds?: number;
+}): Promise<VerifySignatureResult>;
+
+export { type CallContext, type CallType, type Charge, type ChargeCreditsCallback, type ChargeResult, type CreateSessionBody, type CreateSiteBody, type CreatedSite, type Credits, DEFAULT_API_BASE_URL, type Export, type ExportStatus, type GetCreditsCallback, type GetUserCallback, type GetUserIdFromRequest, type HandlerErrorInfo, InvalidCallbackResultError, type LedgerEntry, type LedgerEntryDetail, type LedgerEntryStatus, type LedgerEntryType, MAX_SIGNATURES, type NodeHandler, type NodeRequest, type Page, type PageQuery, PagedList, type ParsedSignatureHeader, type PartnerApi, type PartnerApiErrorCode, type PartnerResponse, type Price, REQUEST_ID_HEADER, Relume, RelumeError, type RelumeErrorCode, type RelumeOptions, type RelumeResponse, type Reversal, type ReversalReason, type ReversalResult, type ReverseChargeCallback, SIGNATURE_HEADER, SIGNATURE_TOLERANCE_SECONDS, type Session, type SignatureFailure, type Site, type UsageGroup, type UsageParams, type UsageRow, type UsageTotals, type User, type UserProfile, type UserStatus, type VerifySignatureResult, computeSignature, parseSignatureHeader, signCall, verifySignature };