@c15t/node-sdk 3.0.0-alpha.3 → 3.0.0-alpha.5

package/dist-types/errors.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Error codes and the error classes the client returns or throws.
+ *
+ * API codes are the backend's own, copied verbatim from `cause.code` in its
+ * error body. Client codes describe failures that happen on this side of the
+ * wire. Both stay SCREAMING_CASE so a caller sees one vocabulary.
+ */
+/**
+ * Every code the c15t backend can put in `cause.code`.
+ *
+ * Each method narrows this to the codes its endpoint can actually return.
+ */
+export declare const C15T_API_ERROR_CODES: readonly ['BAD_REQUEST', 'CHOICE_OUT_OF_SCOPE', 'CHOICE_PREFERENCE_MISMATCH', 'CONFLICT', 'DATABASE_ERROR', 'EXTERNAL_ID_REQUIRED', 'INPUT_VALIDATION_FAILED', 'NOT_FOUND', 'POLICY_SNAPSHOT_EXPIRED', 'POLICY_SNAPSHOT_INVALID', 'POLICY_SNAPSHOT_REQUIRED', 'PURPOSE_NOT_ALLOWED', 'SERVICE_UNAVAILABLE', 'STALE_POLICY', 'SUBJECT_CONFLICT', 'TYPE_REQUIRED', 'UNAUTHORIZED'];
+/** A code the c15t backend can return. */
+export type C15tApiErrorCode = (typeof C15T_API_ERROR_CODES)[number];
+/**
+ * Failures every method can return, whichever endpoint it calls.
+ *
+ * - `INVALID_INPUT`: the input failed validation; nothing was sent.
+ * - `MISSING_API_KEY`: the endpoint needs an API key and the client has none;
+ *   nothing was sent.
+ * - `NETWORK_ERROR`: the request failed before a response arrived.
+ * - `TIMEOUT`: one attempt exceeded `timeoutMs`, body read included.
+ * - `ABORTED`: the caller's `signal` aborted the call.
+ * - `UNEXPECTED_RESPONSE`: a response this endpoint does not document, such as
+ *   a proxy's HTML error page, an undeclared error code (kept in
+ *   `serverCode`), or a body that could not be decoded.
+ */
+export declare const C15T_CLIENT_ERROR_CODES: readonly ['ABORTED', 'INVALID_INPUT', 'MISSING_API_KEY', 'NETWORK_ERROR', 'TIMEOUT', 'UNEXPECTED_RESPONSE'];
+/** A failure produced by the client rather than the backend. */
+export type C15tClientErrorCode = (typeof C15T_CLIENT_ERROR_CODES)[number];
+/** Any code a {@link C15tError} can carry. */
+export type C15tErrorCode = C15tApiErrorCode | C15tClientErrorCode;
+/** Why the backend refused a consent as `STALE_POLICY`. */
+export type StalePolicyReason = 'decision-mismatch' | 'incomplete-inputs' | 'policy-changed';
+/**
+ * Narrows a wire value to a documented stale-policy reason.
+ * @internal
+ */
+export declare const isStalePolicyReason: (value: unknown) => value is StalePolicyReason;
+/** One input validation problem, as the schema reported it. */
+export interface C15tIssue {
+    readonly message: string;
+    /** Path into the input, such as `['preferences', 'analytics']`. */
+    readonly path?: readonly PropertyKey[];
+}
+/**
+ * `reason` is only ever set for `STALE_POLICY`, so it is typed that way: a
+ * `C15tError<'NOT_FOUND'>` has no reason to read.
+ */
+type ReasonFor<Code extends string> = Code extends 'STALE_POLICY' ? StalePolicyReason | undefined : undefined;
+/** Fields used to build a {@link C15tError}. */
+export interface C15tErrorInit<Code extends string> {
+    readonly code: Code;
+    readonly message: string;
+    readonly status?: number | undefined;
+    readonly reason?: StalePolicyReason | undefined;
+    readonly requestId?: string | undefined;
+    readonly retryable?: boolean | undefined;
+    readonly issues?: readonly C15tIssue[] | undefined;
+    readonly serverCode?: string | undefined;
+    readonly cause?: unknown;
+}
+/**
+ * A failed call.
+ *
+ * Methods return it inside `{ ok: false, error }` rather than throwing it;
+ * {@link unwrap} throws it. `Code` is the union of codes the failing method
+ * can produce, so a `switch (error.code)` is checked for exhaustiveness.
+ *
+ * @example
+ * ```ts
+ * const result = await c15t.subjects.get(id);
+ * if (!result.ok) {
+ *   switch (result.error.code) {
+ *     case 'NOT_FOUND':
+ *       return null;
+ *     default:
+ *       throw result.error;
+ *   }
+ * }
+ * ```
+ */
+export declare class C15tError<Code extends string = C15tErrorCode> extends Error {
+    readonly name = "C15tError";
+    /** Stable, machine-readable failure code. */
+    readonly code: Code;
+    /** HTTP status, when a response arrived. */
+    readonly status: number | undefined;
+    /** Refinement of `STALE_POLICY`; `undefined` for every other code. */
+    readonly reason: ReasonFor<Code>;
+    /**
+     * The `x-request-id` the call sent, for matching backend logs. Absent when
+     * nothing was sent (`INVALID_INPUT`, `MISSING_API_KEY`).
+     */
+    readonly requestId: string | undefined;
+    /**
+     * Whether repeating the same call could succeed. The client already
+     * retried idempotent endpoints before returning this.
+     */
+    readonly retryable: boolean;
+    /** Validation problems, set for `INVALID_INPUT`. */
+    readonly issues: readonly C15tIssue[] | undefined;
+    /**
+     * The raw `cause.code` when the backend sent one this endpoint does not
+     * document. Set only for `UNEXPECTED_RESPONSE`.
+     */
+    readonly serverCode: string | undefined;
+    constructor(init: C15tErrorInit<Code>);
+    /** Plain object for logging and serialization. `cause` is left out. */
+    toJSON(): {
+        readonly name: 'C15tError';
+        readonly code: Code;
+        readonly message: string;
+        readonly status: number | undefined;
+        readonly reason: ReasonFor<Code>;
+        readonly requestId: string | undefined;
+        readonly retryable: boolean;
+        readonly issues: readonly C15tIssue[] | undefined;
+        readonly serverCode: string | undefined;
+    };
+}
+/**
+ * Checks whether a value is a {@link C15tError}, optionally with one of the
+ * given codes.
+ *
+ * @param error - Any caught value.
+ * @param codes - Codes to match. With none, any `C15tError` matches.
+ * @returns `true` when `error` is a `C15tError` whose code is in `codes`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   unwrap(await c15t.subjects.get(id));
+ * } catch (error) {
+ *   if (isC15tError(error, 'NOT_FOUND')) {
+ *     // error.code is 'NOT_FOUND'
+ *   }
+ * }
+ * ```
+ */
+export declare function isC15tError<const Codes extends readonly C15tErrorCode[]>(error: unknown, ...codes: Codes): error is C15tError<Codes extends readonly [] ? C15tErrorCode : Codes[number]>;
+export {};

package/dist-types/index.d.ts

@@ -1,43 +1,16 @@
-import { C15TClient } from './client.js';
-import type { C15TClientOptions } from './types.js';
 /**
- * Creates a type-safe C15T client instance
+ * Typed client for the c15t consent API, for server code.
  *
- * @param options - Configuration options for the client. If not provided,
- *                  falls back to C15T_API_URL and C15T_API_TOKEN environment variables.
- * @returns A C15TClient instance for interacting with the C15T API
- *
- * @example
- * ```typescript
- * // Auto-configure from environment variables
- * const client = c15tClient();
- *
- * // Or provide explicit options
- * const client = c15tClient({
- *   baseUrl: "https://api.example.com",
- *   token: "your-auth-token"
- * });
- *
- * // Check API status
- * const status = await client.meta.status();
- *
- * // Initialize consent manager
- * const init = await client.meta.init();
- *
- * // Create a subject with consent
- * const subject = await client.subjects.create({
- *   type: 'cookie_banner',
- *   subjectId: 'sub_123',
- *   domain: 'example.com',
- *   preferences: { analytics: true },
- *   givenAt: Date.now(),
- * });
- * ```
+ * @packageDocumentation
  */
-export declare const c15tClient: (options?: C15TClientOptions) => C15TClient;
-export type { CheckConsentOutput, CheckConsentQuery, ConsentCheckResult, ConsentItem, GetSubjectInput, GetSubjectOutput, GetSubjectParams, GetSubjectQuery, InitOutput, ListSubjectsOutput, ListSubjectsQuery, PatchSubjectFullInput, PatchSubjectOutput, PostSubjectInput, PostSubjectOutput, StatusOutput, SubjectItem, } from '@c15t/schema/types';
-export { C15TClient } from './client.js';
-export { C15TError, isC15TError } from './error.js';
-export type { FetcherContext } from './fetcher.js';
-export { createResponseContext, fetcher, resolveUrl } from './fetcher.js';
-export type { C15TClientOptions, FetchOptions, ResponseContext, RetryConfig, } from './types.js';
+export { createC15tClient } from './client.js';
+export type { C15tClient, C15tConsents, C15tExperiments, C15tLegalDocuments, C15tPublicClient, C15tPublicSubjects, C15tSubjects, } from './client.js';
+export type { C15tCheckConsentInput, C15tCheckConsentOutput, C15tCreateSubjectInput, C15tExperimentSummaryRequest, C15tGetSubjectRequest, C15tIdentifySubjectInput, C15tInitRequest, C15tManifestRequest, C15tManifestResult, C15tPublishLegalDocumentInput, } from './contract.js';
+export { C15tConfigurationError } from './configuration-error.js';
+export type { C15tConfigurationIssue } from './configuration-error.js';
+export { C15T_API_ERROR_CODES, C15T_CLIENT_ERROR_CODES, C15tError, isC15tError, } from './errors.js';
+export type { C15tApiErrorCode, C15tClientErrorCode, C15tErrorCode, C15tIssue, StalePolicyReason, } from './errors.js';
+export type { C15tCallOptions, C15tClientOptions, C15tRequestEvent, C15tRetryOptions, } from './options.js';
+export { unwrap } from './result.js';
+export type { C15tDataOf, C15tErrorCodeOf, C15tFailure, C15tResult, C15tSuccess, } from './result.js';
+export type { ConsentCheckResult, ConsentItem, ConsentManifest, ConsentPolicyType, ExperimentArmSummary, ExperimentSummaryOutput, GetSubjectOutput, InitOutput, LegalDocumentCurrentOutput, LegalDocumentPolicyType, ListSubjectsOutput, PatchSubjectOutput, PostSubjectOutput, StatusOutput, SubjectItem, } from '@c15t/schema/types';

package/dist-types/options.d.ts

@@ -0,0 +1,152 @@
+import type { C15tConfigurationIssue } from './configuration-error.js';
+import type { C15tError } from './errors.js';
+/** Retry behaviour for idempotent endpoints. */
+export interface C15tRetryOptions {
+    /**
+     * Attempts after the first, for retryable failures only.
+     * @default 2
+     */
+    readonly maxRetries?: number;
+    /**
+     * Upper bound of the first backoff, in milliseconds. Each retry doubles it,
+     * and the actual delay is a random value below the bound (full jitter).
+     * Must be an integer from 0 to 2147483647.
+     * @default 200
+     */
+    readonly initialDelayMs?: number;
+    /**
+     * Longest the client waits before a retry, in milliseconds. A
+     * `Retry-After` longer than this ends retrying instead.
+     * Must be an integer from 0 to 2147483647.
+     * @default 5000
+     */
+    readonly maxDelayMs?: number;
+}
+/** What happened during one call, for logging and metrics. */
+export type C15tRequestEvent = {
+    readonly type: 'request';
+    readonly method: string;
+    readonly path: string;
+    readonly requestId: string;
+    /** 0 for the first attempt. */
+    readonly attempt: number;
+} | {
+    readonly type: 'response';
+    readonly method: string;
+    readonly path: string;
+    readonly requestId: string;
+    readonly attempt: number;
+    readonly status: number;
+    readonly durationMs: number;
+} | {
+    readonly type: 'retry';
+    readonly method: string;
+    readonly path: string;
+    readonly requestId: string;
+    /** The attempt that failed. */
+    readonly attempt: number;
+    readonly delayMs: number;
+    readonly error: C15tError;
+};
+/** Options for {@link createC15tClient}. */
+export interface C15tClientOptions {
+    /**
+     * Where the c15t backend is mounted, path included, such as
+     * `https://example.com/api/c15t` or your hosted instance URL.
+     */
+    readonly baseUrl: string | URL;
+    /**
+     * API key, sent as `Authorization: Bearer`. Required for
+     * `subjects.list`, `experiments.summary` and `legalDocuments.publish`;
+     * a client created without one does not have those methods.
+     *
+     * The client reads no environment variables. Pass the key explicitly.
+     */
+    readonly apiKey?: string | undefined;
+    /**
+     * `fetch` implementation. Defaults to `globalThis.fetch`. Use it for
+     * tracing, proxies or tests.
+     */
+    readonly fetch?: typeof globalThis.fetch;
+    /** Headers sent with every request. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Deadline for one attempt in milliseconds, response body included.
+     * Must be an integer from 1 to 2147483647.
+     * @default 10000
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Retry behaviour for idempotent endpoints, or `false` to never retry.
+     */
+    readonly retry?: C15tRetryOptions | false;
+    /**
+     * Called for each request, response and retry. Errors it throws are
+     * ignored.
+     */
+    readonly onEvent?: (event: C15tRequestEvent) => void;
+}
+/** Options accepted by every method as its last argument. */
+export interface C15tCallOptions {
+    /** Aborts the call, including a pending retry. Resolves as `ABORTED`. */
+    readonly signal?: AbortSignal;
+    /** Overrides the client's `timeoutMs` for this call. */
+    readonly timeoutMs?: number;
+    /** Headers for this call, merged over the client's. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Overrides the client's retry behaviour for this call. */
+    readonly retry?: C15tRetryOptions | false;
+    /**
+     * `x-request-id` to send, such as the id of the request being handled.
+     * Defaults to a random UUID.
+     */
+    readonly requestId?: string;
+}
+/** Retry settings with every default applied. */
+export interface ResolvedRetry {
+    readonly maxRetries: number;
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+}
+/** Client options after decoding. */
+export interface ResolvedOptions {
+    readonly baseUrl: URL;
+    readonly apiKey: string | undefined;
+    readonly fetch: typeof globalThis.fetch;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly timeoutMs: number;
+    readonly retry: ResolvedRetry;
+    readonly onEvent: ((event: C15tRequestEvent) => void) | undefined;
+}
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+export declare const MAX_RETRIES_LIMIT = 10;
+export declare const NO_RETRY: ResolvedRetry;
+/**
+ * Decodes retry options. Shared with per-call options, which is why it takes
+ * the option path to report.
+ */
+export declare const decodeRetry: (value: unknown, option: string, issues: C15tConfigurationIssue[], fallback?: ResolvedRetry) => ResolvedRetry;
+/**
+ * Decodes client options from `unknown`.
+ *
+ * TypeScript catches most mistakes at the call site, but JavaScript callers
+ * and options assembled at runtime reach the same code, so every option is
+ * checked here and every problem is reported in one throw.
+ *
+ * @throws {C15tConfigurationError} When any option is invalid.
+ */
+export declare const decodeOptions: (options: unknown) => ResolvedOptions;
+/** Call options after decoding, with client defaults applied. */
+export interface ResolvedCallOptions {
+    readonly signal: AbortSignal | undefined;
+    readonly timeoutMs: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly retry: ResolvedRetry;
+    readonly requestId: string;
+}
+/**
+ * Decodes per-call options. Unlike client options, a bad value here is
+ * reported as an `INVALID_INPUT` result rather than thrown, because methods
+ * never throw.
+ */
+export declare const decodeCallOptions: (value: unknown, client: ResolvedOptions, issues: C15tConfigurationIssue[]) => ResolvedCallOptions;

package/dist-types/path.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Names of the `:param` segments in a route template.
+ *
+ * @example
+ * ```ts
+ * type Names = PathParamNames<'/experiments/:id/summary'>; // 'id'
+ * ```
+ */
+export type PathParamNames<Path extends string> = Path extends `${string}:${infer Param}/${infer Rest}` ? Param | PathParamNames<`/${Rest}`> : Path extends `${string}:${infer Param}` ? Param : never;
+/** The values a route template needs, one string per `:param`. */
+export type PathParams<Path extends string> = {
+    readonly [Name in PathParamNames<Path>]: string;
+};
+/**
+ * Fills a route template's `:param` segments.
+ *
+ * Every value is percent-encoded, so an id containing `/`, `?` or `#` stays
+ * one path segment instead of changing the route.
+ *
+ * @param template - Route template, such as `/subjects/:id`.
+ * @param params - One string per `:param`.
+ * @returns The path with every segment filled.
+ */
+export declare const buildPath: <Path extends string>(template: Path, params: PathParams<Path>) => string;

package/dist-types/result.d.ts

@@ -0,0 +1,77 @@
+import type { C15tClientErrorCode, C15tError } from './errors.js';
+/** A call that succeeded. */
+export interface C15tSuccess<Data> {
+    readonly ok: true;
+    readonly data: Data;
+    /** HTTP status of the response. */
+    readonly status: number;
+    /** The `x-request-id` the call sent. */
+    readonly requestId: string;
+    readonly headers: Headers;
+}
+/** A call that failed. */
+export interface C15tFailure<Code extends string> {
+    readonly ok: false;
+    readonly error: C15tError<Code>;
+}
+/**
+ * What every client method resolves to. Methods never reject.
+ *
+ * `ApiCode` lists the backend codes the method's endpoint can return; the
+ * client's own codes are always included.
+ *
+ * @example
+ * ```ts
+ * const result = await c15t.subjects.get(id);
+ * if (result.ok) {
+ *   result.data.consents; // narrowed: data exists, error does not
+ * } else {
+ *   result.error.code; // 'NOT_FOUND' | 'DATABASE_ERROR' | C15tClientErrorCode
+ * }
+ * ```
+ */
+export type C15tResult<Data, ApiCode extends string = never> = C15tSuccess<Data> | C15tFailure<ApiCode | C15tClientErrorCode>;
+/** Anything that returns a {@link C15tResult}, sync or async. */
+type ResultReturning = (...args: never[]) => C15tResult<unknown, string> | Promise<C15tResult<unknown, string>>;
+/**
+ * The `data` type of a client method.
+ *
+ * @example
+ * ```ts
+ * type Subject = C15tDataOf<typeof c15t.subjects.get>;
+ * ```
+ */
+export type C15tDataOf<Method extends ResultReturning> = Extract<Awaited<ReturnType<Method>>, {
+    ok: true;
+}> extends C15tSuccess<infer Data> ? Data : never;
+/**
+ * Every error code a client method can return.
+ *
+ * @example
+ * ```ts
+ * type GetSubjectError = C15tErrorCodeOf<typeof c15t.subjects.get>;
+ * ```
+ */
+export type C15tErrorCodeOf<Method extends ResultReturning> = Extract<Awaited<ReturnType<Method>>, {
+    ok: false;
+}> extends C15tFailure<infer Code> ? Code : never;
+/**
+ * Returns the data of a successful result, or throws its {@link C15tError}.
+ *
+ * Use it where a failure should abort the surrounding work, such as a job
+ * that has its own retry.
+ *
+ * @param result - A client method's result.
+ * @returns The result's `data`.
+ * @throws {C15tError} The result's error, with its code narrowed to the
+ * method's codes.
+ *
+ * @example
+ * ```ts
+ * const { results } = unwrap(
+ *   await c15t.consents.check({ externalId, types: ['marketing_communications'] })
+ * );
+ * ```
+ */
+export declare const unwrap: <Data, Code extends string>(result: C15tSuccess<Data> | C15tFailure<Code>) => Data;
+export {};

package/dist-types/testing.d.ts

@@ -1,110 +1,101 @@
 /**
- * Testing utilities for @c15t/node-sdk
+ * Test helpers for code that uses `@c15t/node-sdk`.
  *
- * These utilities help users mock the C15T client in their tests.
+ * `createMockC15tClient` returns a full {@link C15tClient} whose methods call
+ * the handlers you pass. Handler types come from the client, so a handler
+ * that returns the wrong data or an error code its method cannot produce is
+ * a type error.
  *
  * @example
- * ```typescript
- * import { createMockClient, createMockResponse } from '@c15t/node-sdk/testing';
+ * ```ts
+ * import { createMockC15tClient, err, ok } from '@c15t/node-sdk/testing';
  *
- * const mockClient = createMockClient({
- *   getSubject: async () => createMockResponse({ id: 'sub_123', consents: [] }),
+ * const c15t = createMockC15tClient({
+ *   consents: {
+ *     check: ({ types }) =>
+ *       ok({
+ *         results: Object.fromEntries(
+ *           types.map((type) => [type, { hasConsent: true, isLatestPolicy: true }])
+ *         ),
+ *       }),
+ *   },
+ *   subjects: { get: () => err('NOT_FOUND') },
  * });
- *
- * // Use mockClient in your tests
- * const result = await mockClient.getSubject('sub_123');
- * expect(result.data?.id).toBe('sub_123');
  * ```
  */
-import type { ResponseContext } from './types.js';
+import type { ConsentPolicyType } from '@c15t/schema/types';
+import type { C15tClient, C15tExperiments, C15tLegalDocuments, C15tSubjects } from './client.js';
+import type { C15tCheckConsentInput } from './contract.js';
+import type { C15tErrorCode, C15tIssue, StalePolicyReason } from './errors.js';
+import type { C15tCallOptions } from './options.js';
+import type { C15tFailure, C15tResult, C15tSuccess } from './result.js';
+type Awaitable<Value> = Value | Promise<Value>;
+/** A handler with the same arguments as `Method`, sync or async. */
+export type C15tMockHandler<Method> = Method extends (...args: infer Args) => Promise<infer Result> ? (...args: Args) => Awaitable<Result> : never;
 /**
- * Creates a mock ResponseContext for testing
- *
- * @param data - The data to return in the response
- * @param options - Optional configuration for the mock response
- * @returns A ResponseContext object
- *
- * @example
- * ```typescript
- * const response = createMockResponse({ id: 'sub_123' });
- * expect(response.ok).toBe(true);
- * expect(response.data?.id).toBe('sub_123');
- * ```
+ * `consents.check` is generic over the requested types, which a plain
+ * handler cannot be. Its handler returns results keyed by string; the mock
+ * hands them back under the caller's narrowed type.
  */
-export declare const createMockResponse: <T>(data: T, options?: {
-    ok?: boolean;
-    error?: {
-        message: string;
-        status: number;
-        code?: string;
-        details?: Record<string, unknown> | null;
+export type C15tMockCheckConsentHandler = (input: C15tCheckConsentInput<readonly ConsentPolicyType[]>, options?: C15tCallOptions) => Awaitable<C15tResult<{
+    readonly results: Readonly<Record<string, {
+        readonly hasConsent: boolean;
+        readonly isLatestPolicy: boolean;
+    }>>;
+}, 'DATABASE_ERROR' | 'EXTERNAL_ID_REQUIRED' | 'TYPE_REQUIRED'>>;
+/** Handlers for {@link createMockC15tClient}. Any method can be left out. */
+export interface C15tMockHandlers {
+    readonly status?: C15tMockHandler<C15tClient['status']>;
+    readonly init?: C15tMockHandler<C15tClient['init']>;
+    readonly manifest?: C15tMockHandler<C15tClient['manifest']>;
+    readonly subjects?: {
+        readonly [Name in keyof C15tSubjects]?: C15tMockHandler<C15tSubjects[Name]>;
+    };
+    readonly consents?: {
+        readonly check?: C15tMockCheckConsentHandler;
     };
-    response?: Response;
-}) => ResponseContext<T>;
+    readonly experiments?: {
+        readonly [Name in keyof C15tExperiments]?: C15tMockHandler<C15tExperiments[Name]>;
+    };
+    readonly legalDocuments?: {
+        readonly [Name in keyof C15tLegalDocuments]?: C15tMockHandler<C15tLegalDocuments[Name]>;
+    };
+}
 /**
- * Creates a mock error ResponseContext for testing
+ * Builds a successful result.
  *
- * @param error - The error details
- * @returns A ResponseContext object representing an error
- *
- * @example
- * ```typescript
- * const response = createMockErrorResponse({
- *   message: 'Not found',
- *   status: 404,
- *   code: 'NOT_FOUND',
- * });
- * expect(response.ok).toBe(false);
- * expect(response.error?.status).toBe(404);
- * ```
- */
-export declare const createMockErrorResponse: <T = unknown>(error: {
-    message: string;
-    status: number;
-    code?: string;
-    details?: Record<string, unknown> | null;
-}) => ResponseContext<T>;
-/**
- * Type for mock method implementations
+ * @param data - The result's data.
+ * @param init - Optional status, request id and headers.
  */
-export type MockMethodImplementation<TInput, TOutput> = (input: TInput) => ResponseContext<TOutput> | Promise<ResponseContext<TOutput>>;
+export declare const ok: <Data>(data: Data, init?: {
+    readonly status?: number;
+    readonly requestId?: string;
+    readonly headers?: ConstructorParameters<typeof Headers>[0];
+}) => C15tSuccess<Data>;
 /**
- * Type for mock client overrides
+ * Builds a failed result. The code is checked against the method the
+ * handler belongs to.
+ *
+ * @param code - Error code, such as `NOT_FOUND`.
+ * @param init - Optional message, status and other error fields.
  */
-export interface MockClientOverrides {
-    status?: MockMethodImplementation<void, unknown>;
-    init?: MockMethodImplementation<void, unknown>;
-    checkConsent?: MockMethodImplementation<unknown, unknown>;
-    createSubject?: MockMethodImplementation<unknown, unknown>;
-    getSubject?: MockMethodImplementation<string, unknown>;
-    patchSubject?: MockMethodImplementation<unknown, unknown>;
-    listSubjects?: MockMethodImplementation<unknown, unknown>;
-}
+export declare const err: <const Code extends C15tErrorCode>(code: Code, init?: {
+    readonly message?: string;
+    readonly status?: number;
+    readonly reason?: Code extends 'STALE_POLICY' ? StalePolicyReason : never;
+    readonly requestId?: string;
+    readonly retryable?: boolean;
+    readonly issues?: readonly C15tIssue[];
+    readonly serverCode?: string;
+}) => C15tFailure<Code>;
 /**
- * Creates a mock C15T client for testing
+ * Creates a client whose methods call the given handlers.
  *
- * @param overrides - Method implementations to override
- * @returns A mock client object
+ * A method without a handler rejects with an error naming it, so a test
+ * fails loudly when code calls something the test did not expect.
  *
- * @example
- * ```typescript
- * const mockClient = createMockClient({
- *   getSubject: async (id) => createMockResponse({
- *     id,
- *     externalId: 'user_123',
- *     consents: [],
- *   }),
- *   checkConsent: async () => createMockResponse({
- *     results: { analytics: { hasConsent: true } },
- *   }),
- * });
- *
- * // Use in tests
- * const result = await mockClient.getSubject('sub_123');
- * ```
- */
-export declare const createMockClient: (overrides?: MockClientOverrides) => any;
-/**
- * Type representing the mock client returned by createMockClient
+ * @param handlers - Handlers by namespace and method name.
+ * @returns A full {@link C15tClient}.
  */
-export type MockC15TClient = ReturnType<typeof createMockClient>;
+export declare const createMockC15tClient: (handlers?: C15tMockHandlers) => C15tClient;
+export {};

package/dist-types/transport.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Sends one endpoint call: validation, auth, retries, timeouts and response
+ * classification. Every outcome resolves as a result; nothing here throws to
+ * the caller.
+ */
+import type { Endpoint } from './contract.js';
+import type { C15tApiErrorCode } from './errors.js';
+import type { ResolvedOptions } from './options.js';
+import type { C15tResult } from './result.js';
+/**
+ * Calls one endpoint.
+ *
+ * @param options - Decoded client options.
+ * @param endpoint - The route to call.
+ * @param input - The endpoint's input, validated before anything is sent.
+ * @param rawCallOptions - The caller's per-call options, decoded here.
+ * @returns The call's result. Never rejects.
+ */
+export declare const send: <Path extends string, Input, Data, Code extends C15tApiErrorCode>(options: ResolvedOptions, endpoint: Endpoint<Path, Input, Data, Code>, input: Input, rawCallOptions: unknown) => Promise<C15tResult<Data, Code>>;

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.0.0-alpha.3";
+export declare const version = "3.0.0-alpha.5";