@apostra/sdk 0.0.0-stage → 0.37.0

package/dist/generated/types.gen.js

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './generated/client.js';
+export { operations, version } from './generated/metadata.js';
+export type { AdcpError, JsonValue } from './generated/types.gen.js';
+export * from './transport.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './generated/client.js';
+export { operations, version } from './generated/metadata.js';
+export * from './transport.js';

package/dist/transport.d.ts

@@ -0,0 +1,142 @@
+import type { OperationTypes } from './generated/client.js';
+import { type OperationId, operations } from './generated/metadata.js';
+import type { AdcpError, InFlightReceipt, OpenCampaignsPageSuccessPageHumanHandoffRequired } from './generated/types.gen.js';
+export type TokenProvider = () => string | Promise<string>;
+export type M2mTokenProviderOptions = {
+    clientId: string;
+    clientSecret: string;
+    scope: string | string[];
+    /** Override fetch for testing or an application-owned HTTP implementation. */
+    fetch?: typeof globalThis.fetch;
+    /** Deadline for an M2M token refresh. Defaults to 30 seconds. */
+    timeoutMs?: number;
+};
+export type ClientOptions = {
+    /** Supply exactly one credential source. Providers own acquisition/refresh. */
+    apiKey?: string;
+    accessToken?: string;
+    tokenProvider?: TokenProvider;
+    accountId?: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    /** Retry transient read failures and caller-keyed writes this many times. */
+    maxRetries?: number;
+};
+export type RequestOptions = {
+    accountId?: string;
+    /** Required by generated write methods. Never generated or replaced by the SDK. */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+export type WriteRequestOptions = RequestOptions & {
+    idempotencyKey: string;
+};
+type WriteOperationId = {
+    [O in OperationId]: (typeof operations)[O]['idempotencyKey'] extends true ? O : never;
+}[OperationId];
+type ReadOperationId = Exclude<OperationId, WriteOperationId>;
+export type ResponseDetails<T> = {
+    data: T;
+    status: number;
+    headers: Headers;
+    requestId: string | null;
+};
+export type HumanHandoff = Pick<OpenCampaignsPageSuccessPageHumanHandoffRequired, 'kind' | 'url' | 'expiresAt' | 'resume'>;
+export type ApostraErrorCode = 'UNAUTHENTICATED' | 'AUTHENTICATION_FAILED' | 'ACCESS_DENIED' | 'NOT_FOUND' | 'CONFLICT' | 'RATE_LIMITED' | 'VALIDATION_FAILED' | (string & {});
+type Recovery = 'transient' | 'correctable' | 'terminal';
+export declare class ApostraError extends Error {
+    readonly status: number;
+    readonly error: AdcpError;
+    readonly requestId: string | null;
+    readonly code: ApostraErrorCode;
+    readonly recovery: Recovery;
+    readonly retryAfter: number | null;
+    readonly retryable: boolean;
+    constructor(status: number, error: AdcpError, requestId: string | null);
+}
+export declare class AuthenticationError extends ApostraError {
+}
+export declare class PermissionError extends ApostraError {
+}
+export declare class NotFoundError extends ApostraError {
+}
+export declare class ConflictError extends ApostraError {
+}
+export declare class RateLimitError extends ApostraError {
+}
+export declare class ValidationError extends ApostraError {
+}
+/** @deprecated This compatibility export is never thrown by the transport. */
+export declare class UnsupportedCapabilityError extends Error {
+}
+export declare class ConnectionError extends Error {
+    readonly code: "CONNECTION_ERROR";
+    readonly recovery: "transient";
+    readonly retryAfter: null;
+    readonly retryable = true;
+    readonly requestId: null;
+    constructor(cause: unknown);
+}
+export declare class TimeoutError extends Error {
+    readonly code: "TIMEOUT";
+    readonly recovery: "transient";
+    readonly retryAfter: null;
+    readonly retryable = true;
+    readonly requestId: null;
+    constructor(cause: unknown);
+}
+export declare class ProtocolError extends Error {
+    readonly status: number;
+    readonly requestId: string | null;
+    constructor(status: number, requestId: string | null);
+}
+/**
+ * The server accepted a write but cannot yet honestly report its completion.
+ *
+ * Callers retain the original operation-specific idempotency key; the SDK
+ * never makes another request or creates a replacement key.
+ */
+export declare class InFlightReceiptError extends Error {
+    readonly requestId: string | null;
+    readonly retryAfterMs: number | null;
+    readonly receipt: InFlightReceipt;
+    readonly status = 202;
+    constructor(requestId: string | null, retryAfterMs: number | null, receipt: InFlightReceipt);
+}
+/**
+ * Acquire and cache an OAuth client-credentials token for server-side use.
+ *
+ * The returned provider performs one refresh for concurrent callers and refreshes
+ * 60 seconds before expiry. It never persists or logs a client secret or token.
+ */
+export declare function m2mTokenProvider({ clientId: rawClientId, clientSecret: rawClientSecret, scope: rawScope, fetch: suppliedFetch, timeoutMs: rawTimeoutMs, }: M2mTokenProviderOptions): TokenProvider;
+export declare class Transport {
+    #private;
+    constructor(options?: ClientOptions);
+    protected request<T>(operation: OperationId, input: object, options?: RequestOptions): Promise<T>;
+    /** Typed dispatch for CLI reuse, including response headers. */
+    requestDetailed<O extends WriteOperationId>(operation: O, input: OperationTypes[O]['input'], options: WriteRequestOptions): Promise<ResponseDetails<OperationTypes[O]['result']>>;
+    requestDetailed<O extends ReadOperationId>(operation: O, input: OperationTypes[O]['input'], options?: RequestOptions): Promise<ResponseDetails<OperationTypes[O]['result']>>;
+    private perform;
+}
+/** Re-invoke a caller-owned keyed write until an in-flight receipt settles. */
+export declare function settle<T>(run: (signal: AbortSignal) => Promise<T>, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<T>;
+/** Visit pages while preserving the exact caller-owned query and cursor rules. */
+export declare function paginate<T>(read: (cursor: string | undefined, signal?: AbortSignal) => Promise<T>, next: (page: T) => string | null | undefined, signal?: AbortSignal): AsyncGenerator<T>;
+/** The caller supplies the contract's status predicate and keeps idempotency keys stable. */
+export declare function poll<T>(read: (signal: AbortSignal) => Promise<T>, complete: (result: T) => boolean, options: {
+    signal: AbortSignal;
+    intervalMs?: number;
+}): Promise<T>;
+/** Return an actionable human handoff, or null when no supported URL is present. */
+export declare function getHandoff(result: {
+    humanHandoff?: unknown;
+} | null | undefined): HumanHandoff | null;
+/** Pass only a handoff returned by getHandoff; headless calls simply return its URL. */
+export declare function openHandoff(handoff: HumanHandoff | string, opener?: (url: string) => void | Promise<void>): Promise<string>;
+export {};