@particle-academy/fancy-connector-core 0.13.0 → 0.15.0

package/dist/index.d.cts

@@ -916,6 +916,72 @@ type ConnectorResult<T = unknown> = {
 declare function registerTransport(next: Transport | null): void;
 declare function callConnector<T = unknown>(service: ServiceDescriptor, options: CallOptions): Promise<ConnectorResult<T>>;
 
+/**
+ * A read that resumes from a HOST-HELD cursor, and pages.
+ *
+ * Gmail's push and Drive's channel notifications carry no changes: they say
+ * "something moved", and the follow-up read fetches what did, starting from
+ * the position the HOST stored last time (Gmail's `startHistoryId`, Drive's
+ * `pageToken`). Reading from the delivery's own position instead misses the
+ * very change that caused it. The package holds no state: the host stores the
+ * cursor, passes it in, and persists `cursor.next` when the run succeeds.
+ *
+ * The PHP twin is `CursorRead::read`; both read `fixtures/cursor-read/`.
+ *
+ * The decisions, each pinned by a case:
+ *
+ * - **`next` comes ONLY from the LAST page.** Gmail's `historyId` is the
+ *   mailbox's CURRENT one on every page, and Google says to store it only "if
+ *   you receive no nextPageToken". Taking it after page one would skip every
+ *   page not yet read, silently.
+ * - **Too many pages is refused** (`cursor-overflow`), never a partial read
+ *   with a cursor that skips the rest. The host's answer is a bounded resync.
+ * - **The provider's own "cursor out of range"** (`expiredStatus`, Gmail's
+ *   404) is `cursor-expired`; every OTHER failure is rethrown unchanged, so a
+ *   500 is never mistaken for a lapse.
+ * - **No stored cursor is `cursor-missing`**, and the provider is not called:
+ *   a read with no starting point is a read from the beginning of time.
+ * - `collect` absent is `[]` (Gmail omits `history` when nothing changed); not
+ *   a list is `bad-page`. The cursor and `next` are strings: history ids are
+ *   uint64.
+ */
+declare const CURSOR_READ_REASONS: readonly ["cursor-missing", "cursor-expired", "cursor-overflow", "bad-page"];
+type CursorReadReason = (typeof CURSOR_READ_REASONS)[number];
+type CursorReadSpec = {
+    /** The read's parameter the stored cursor fills (Gmail: `startHistoryId`). */
+    param: string;
+    /** Where the NEXT cursor is read in the last page's data (Gmail: `historyId`). */
+    advanceFrom: string;
+    /** Paging, when the read pages (Gmail: `pageToken` / `nextPageToken`, `history`). */
+    page?: {
+        param: string;
+        from: string;
+        collect: string;
+        maxPages: number;
+    };
+    /** The status the provider answers for a cursor out of range (Gmail: 404). */
+    expiredStatus?: number;
+};
+type CursorReadResult = {
+    data: unknown;
+    cursor: {
+        used: string;
+        next: string | null;
+    };
+};
+/** Refused BY NAME; `reason` is the same string PHP's exception carries. */
+declare class CursorReadError extends Error {
+    readonly reason: CursorReadReason;
+    /** The host's bounded resync, when the caller declared one (Gmail: `newer_than:7d`). */
+    readonly resyncQuery?: string | undefined;
+    constructor(reason: CursorReadReason, message: string, 
+    /** The host's bounded resync, when the caller declared one (Gmail: `newer_than:7d`). */
+    resyncQuery?: string | undefined);
+}
+declare function readWithCursor(spec: CursorReadSpec, cursor: unknown, call: (params: Record<string, string>) => Promise<unknown>, options?: {
+    resyncQuery?: string;
+}): Promise<CursorReadResult>;
+
 /**
  * API drift — being told the provider changed, rather than discovering it.
  *
@@ -1982,11 +2048,27 @@ type CredentialField = {
     /** A hint for an empty field. NEVER a real value. */
     placeholder?: string;
 };
+/** Who performs a setup step. Ships as data: a host mirrors it across JSON. */
+declare const SETUP_ACTORS: readonly ["person", "agent"];
+type SetupActor = (typeof SETUP_ACTORS)[number];
 type SetupStep = {
     title: string;
     /** The step, and the trap in it. A step with no trap named is usually wrong. */
     detail: string;
     url?: string;
+    /** Who does it. Absent means `person` (0.15.0). */
+    actor?: SetupActor;
+    /** What an agent is asked to do. Required when `actor` is `agent`. */
+    prompt?: string;
+    /** Values the person pastes somewhere, e.g. the callback URL. */
+    copy?: {
+        label: string;
+        value: string;
+    }[];
+    /** The credential keys this step yields. */
+    fields?: string[];
+    /** How the person knows the step is done. */
+    done?: string;
 };
 /**
  * The result of a read-only credential check.
@@ -2784,6 +2866,40 @@ type PubSubPushMessage = {
 };
 declare function decodePubSubPush(raw: Uint8Array | string): PubSubPushMessage;
 
+/**
+ * A connector's setup steps, rendered for ONE app.
+ *
+ * A definition is written once for every host, so the values that differ per
+ * host — where its webhooks live, what it calls itself, which connector this
+ * is — are tokens: `{{appUrl}}`, `{{appName}}`, `{{connector}}`, and only
+ * those. Held to `fixtures/setup-render/cases.json`, mirrored in
+ * `php/src/Setup.php`.
+ *
+ * Two refusals, both BY NAME, because each would otherwise reach a person as a
+ * broken instruction that looks deliberate:
+ *
+ * - `unknown-token`: anything else shaped like `{{...}}` — a typo, a spaced
+ *   `{{ appUrl }}`, a token a definition invented. Left in, a person pastes a
+ *   literal brace into a provider console.
+ * - `missing-context`: a token the host gave no (or an empty) value for. Left
+ *   empty, a callback URL becomes `/hooks/twilio` and points nowhere.
+ *
+ * `appUrl` loses ONE trailing slash first, so `{{appUrl}}/hooks` never doubles
+ * it. A context value is inserted once and never expanded again.
+ */
+
+declare const SETUP_TOKENS: readonly ["appUrl", "appName", "connector"];
+type SetupToken = (typeof SETUP_TOKENS)[number];
+declare const SETUP_RENDER_REASONS: readonly ["unknown-token", "missing-context"];
+type SetupRenderReason = (typeof SETUP_RENDER_REASONS)[number];
+type SetupContext = Partial<Record<SetupToken, string>>;
+declare class SetupRenderError extends Error {
+    readonly reason: SetupRenderReason;
+    constructor(reason: SetupRenderReason, message: string);
+}
+/** Render every step for one app: tokens filled, `actor` and `fields` defaulted. */
+declare function renderSetup(steps: readonly SetupStep[], context: SetupContext): SetupStep[];
+
 /**
  * How a connector trigger learns that something happened.
  *
@@ -2946,4 +3062,4 @@ oidc?: OidcExpectation): Promise<WebhookVerification>;
  */
 declare function triggerEvent(trigger: TriggerDescriptor, connection: ResolvedConnection, injected: unknown, config: Record<string, unknown>): unknown;
 
-export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type Attendee, type ByteRange, CANONICAL_METRICS, CONNECTOR_API_VERSION, CONNECTOR_MODES, CREDENTIAL_SCOPES, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type ChallengeHandshake, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, type CredentialScope, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, DELIVERY_DECODE_KINDS, type DeliveryDeclaration, type DeliveryDecode, type DeliveryMechanism, type DeliveryOutcome, type DeliveryRoute, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, FORM_FIELD_JSON_REASONS, type FailureKind, type FakeRequest, type FakeValues, FormFieldJsonError, type FormFieldJsonReason, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type Invite, type InviteMethod, JWT_ALGORITHMS, type JoinTarget, type JoinTargetKind, type Jwk, type JwtVerification, type LeaseAction, type LeaseDeclaration, type LeaseState, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type MimeAttachment, type MimeHeader, type MimeMessage, type MimePart, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, OIDC_JWT_SCHEME_KIND, type OidcExpectation, type OidcJwtScheme, type OidcJwtVerificationSpec, PROBLEM_SEVERITIES, PUBSUB_PUSH_REASONS, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, PubSubPushError, type PubSubPushMessage, type PubSubPushReason, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RecurrenceRule, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SIGNED_URI_RULES, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SignedRequestLine, type SignedUriRule, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyJwtOptions, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, decodeDelivery, decodeFormFieldJson, decodePubSubPush, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isOidcJwtScheme, isOidcJwtSpec, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, normaliseSignedUri, parseInvite, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, secretKeyBytes, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifyJwt, verifyOidcDelivery, verifySharedToken, withResolvedLimit };
+export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type Attendee, type ByteRange, CANONICAL_METRICS, CONNECTOR_API_VERSION, CONNECTOR_MODES, CREDENTIAL_SCOPES, CURSOR_READ_REASONS, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type ChallengeHandshake, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, type CredentialScope, CursorReadError, type CursorReadReason, type CursorReadResult, type CursorReadSpec, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, DELIVERY_DECODE_KINDS, type DeliveryDeclaration, type DeliveryDecode, type DeliveryMechanism, type DeliveryOutcome, type DeliveryRoute, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, FORM_FIELD_JSON_REASONS, type FailureKind, type FakeRequest, type FakeValues, FormFieldJsonError, type FormFieldJsonReason, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type Invite, type InviteMethod, JWT_ALGORITHMS, type JoinTarget, type JoinTargetKind, type Jwk, type JwtVerification, type LeaseAction, type LeaseDeclaration, type LeaseState, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type MimeAttachment, type MimeHeader, type MimeMessage, type MimePart, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, OIDC_JWT_SCHEME_KIND, type OidcExpectation, type OidcJwtScheme, type OidcJwtVerificationSpec, PROBLEM_SEVERITIES, PUBSUB_PUSH_REASONS, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, PubSubPushError, type PubSubPushMessage, type PubSubPushReason, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RecurrenceRule, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SETUP_ACTORS, SETUP_RENDER_REASONS, SETUP_TOKENS, SIGNED_URI_RULES, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupActor, type SetupContext, SetupRenderError, type SetupRenderReason, type SetupStep, type SetupToken, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SignedRequestLine, type SignedUriRule, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyJwtOptions, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, decodeDelivery, decodeFormFieldJson, decodePubSubPush, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isOidcJwtScheme, isOidcJwtSpec, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, normaliseSignedUri, parseInvite, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, readWithCursor, registerConnectionHost, registerTransport, render, renderSetup, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, secretKeyBytes, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifyJwt, verifyOidcDelivery, verifySharedToken, withResolvedLimit };

package/dist/index.d.ts

@@ -916,6 +916,72 @@ type ConnectorResult<T = unknown> = {
 declare function registerTransport(next: Transport | null): void;
 declare function callConnector<T = unknown>(service: ServiceDescriptor, options: CallOptions): Promise<ConnectorResult<T>>;
 
+/**
+ * A read that resumes from a HOST-HELD cursor, and pages.
+ *
+ * Gmail's push and Drive's channel notifications carry no changes: they say
+ * "something moved", and the follow-up read fetches what did, starting from
+ * the position the HOST stored last time (Gmail's `startHistoryId`, Drive's
+ * `pageToken`). Reading from the delivery's own position instead misses the
+ * very change that caused it. The package holds no state: the host stores the
+ * cursor, passes it in, and persists `cursor.next` when the run succeeds.
+ *
+ * The PHP twin is `CursorRead::read`; both read `fixtures/cursor-read/`.
+ *
+ * The decisions, each pinned by a case:
+ *
+ * - **`next` comes ONLY from the LAST page.** Gmail's `historyId` is the
+ *   mailbox's CURRENT one on every page, and Google says to store it only "if
+ *   you receive no nextPageToken". Taking it after page one would skip every
+ *   page not yet read, silently.
+ * - **Too many pages is refused** (`cursor-overflow`), never a partial read
+ *   with a cursor that skips the rest. The host's answer is a bounded resync.
+ * - **The provider's own "cursor out of range"** (`expiredStatus`, Gmail's
+ *   404) is `cursor-expired`; every OTHER failure is rethrown unchanged, so a
+ *   500 is never mistaken for a lapse.
+ * - **No stored cursor is `cursor-missing`**, and the provider is not called:
+ *   a read with no starting point is a read from the beginning of time.
+ * - `collect` absent is `[]` (Gmail omits `history` when nothing changed); not
+ *   a list is `bad-page`. The cursor and `next` are strings: history ids are
+ *   uint64.
+ */
+declare const CURSOR_READ_REASONS: readonly ["cursor-missing", "cursor-expired", "cursor-overflow", "bad-page"];
+type CursorReadReason = (typeof CURSOR_READ_REASONS)[number];
+type CursorReadSpec = {
+    /** The read's parameter the stored cursor fills (Gmail: `startHistoryId`). */
+    param: string;
+    /** Where the NEXT cursor is read in the last page's data (Gmail: `historyId`). */
+    advanceFrom: string;
+    /** Paging, when the read pages (Gmail: `pageToken` / `nextPageToken`, `history`). */
+    page?: {
+        param: string;
+        from: string;
+        collect: string;
+        maxPages: number;
+    };
+    /** The status the provider answers for a cursor out of range (Gmail: 404). */
+    expiredStatus?: number;
+};
+type CursorReadResult = {
+    data: unknown;
+    cursor: {
+        used: string;
+        next: string | null;
+    };
+};
+/** Refused BY NAME; `reason` is the same string PHP's exception carries. */
+declare class CursorReadError extends Error {
+    readonly reason: CursorReadReason;
+    /** The host's bounded resync, when the caller declared one (Gmail: `newer_than:7d`). */
+    readonly resyncQuery?: string | undefined;
+    constructor(reason: CursorReadReason, message: string, 
+    /** The host's bounded resync, when the caller declared one (Gmail: `newer_than:7d`). */
+    resyncQuery?: string | undefined);
+}
+declare function readWithCursor(spec: CursorReadSpec, cursor: unknown, call: (params: Record<string, string>) => Promise<unknown>, options?: {
+    resyncQuery?: string;
+}): Promise<CursorReadResult>;
+
 /**
  * API drift — being told the provider changed, rather than discovering it.
  *
@@ -1982,11 +2048,27 @@ type CredentialField = {
     /** A hint for an empty field. NEVER a real value. */
     placeholder?: string;
 };
+/** Who performs a setup step. Ships as data: a host mirrors it across JSON. */
+declare const SETUP_ACTORS: readonly ["person", "agent"];
+type SetupActor = (typeof SETUP_ACTORS)[number];
 type SetupStep = {
     title: string;
     /** The step, and the trap in it. A step with no trap named is usually wrong. */
     detail: string;
     url?: string;
+    /** Who does it. Absent means `person` (0.15.0). */
+    actor?: SetupActor;
+    /** What an agent is asked to do. Required when `actor` is `agent`. */
+    prompt?: string;
+    /** Values the person pastes somewhere, e.g. the callback URL. */
+    copy?: {
+        label: string;
+        value: string;
+    }[];
+    /** The credential keys this step yields. */
+    fields?: string[];
+    /** How the person knows the step is done. */
+    done?: string;
 };
 /**
  * The result of a read-only credential check.
@@ -2784,6 +2866,40 @@ type PubSubPushMessage = {
 };
 declare function decodePubSubPush(raw: Uint8Array | string): PubSubPushMessage;
 
+/**
+ * A connector's setup steps, rendered for ONE app.
+ *
+ * A definition is written once for every host, so the values that differ per
+ * host — where its webhooks live, what it calls itself, which connector this
+ * is — are tokens: `{{appUrl}}`, `{{appName}}`, `{{connector}}`, and only
+ * those. Held to `fixtures/setup-render/cases.json`, mirrored in
+ * `php/src/Setup.php`.
+ *
+ * Two refusals, both BY NAME, because each would otherwise reach a person as a
+ * broken instruction that looks deliberate:
+ *
+ * - `unknown-token`: anything else shaped like `{{...}}` — a typo, a spaced
+ *   `{{ appUrl }}`, a token a definition invented. Left in, a person pastes a
+ *   literal brace into a provider console.
+ * - `missing-context`: a token the host gave no (or an empty) value for. Left
+ *   empty, a callback URL becomes `/hooks/twilio` and points nowhere.
+ *
+ * `appUrl` loses ONE trailing slash first, so `{{appUrl}}/hooks` never doubles
+ * it. A context value is inserted once and never expanded again.
+ */
+
+declare const SETUP_TOKENS: readonly ["appUrl", "appName", "connector"];
+type SetupToken = (typeof SETUP_TOKENS)[number];
+declare const SETUP_RENDER_REASONS: readonly ["unknown-token", "missing-context"];
+type SetupRenderReason = (typeof SETUP_RENDER_REASONS)[number];
+type SetupContext = Partial<Record<SetupToken, string>>;
+declare class SetupRenderError extends Error {
+    readonly reason: SetupRenderReason;
+    constructor(reason: SetupRenderReason, message: string);
+}
+/** Render every step for one app: tokens filled, `actor` and `fields` defaulted. */
+declare function renderSetup(steps: readonly SetupStep[], context: SetupContext): SetupStep[];
+
 /**
  * How a connector trigger learns that something happened.
  *
@@ -2946,4 +3062,4 @@ oidc?: OidcExpectation): Promise<WebhookVerification>;
  */
 declare function triggerEvent(trigger: TriggerDescriptor, connection: ResolvedConnection, injected: unknown, config: Record<string, unknown>): unknown;
 
-export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type Attendee, type ByteRange, CANONICAL_METRICS, CONNECTOR_API_VERSION, CONNECTOR_MODES, CREDENTIAL_SCOPES, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type ChallengeHandshake, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, type CredentialScope, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, DELIVERY_DECODE_KINDS, type DeliveryDeclaration, type DeliveryDecode, type DeliveryMechanism, type DeliveryOutcome, type DeliveryRoute, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, FORM_FIELD_JSON_REASONS, type FailureKind, type FakeRequest, type FakeValues, FormFieldJsonError, type FormFieldJsonReason, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type Invite, type InviteMethod, JWT_ALGORITHMS, type JoinTarget, type JoinTargetKind, type Jwk, type JwtVerification, type LeaseAction, type LeaseDeclaration, type LeaseState, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type MimeAttachment, type MimeHeader, type MimeMessage, type MimePart, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, OIDC_JWT_SCHEME_KIND, type OidcExpectation, type OidcJwtScheme, type OidcJwtVerificationSpec, PROBLEM_SEVERITIES, PUBSUB_PUSH_REASONS, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, PubSubPushError, type PubSubPushMessage, type PubSubPushReason, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RecurrenceRule, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SIGNED_URI_RULES, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SignedRequestLine, type SignedUriRule, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyJwtOptions, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, decodeDelivery, decodeFormFieldJson, decodePubSubPush, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isOidcJwtScheme, isOidcJwtSpec, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, normaliseSignedUri, parseInvite, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, secretKeyBytes, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifyJwt, verifyOidcDelivery, verifySharedToken, withResolvedLimit };
+export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type Attendee, type ByteRange, CANONICAL_METRICS, CONNECTOR_API_VERSION, CONNECTOR_MODES, CREDENTIAL_SCOPES, CURSOR_READ_REASONS, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type ChallengeHandshake, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, type CredentialScope, CursorReadError, type CursorReadReason, type CursorReadResult, type CursorReadSpec, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, DELIVERY_DECODE_KINDS, type DeliveryDeclaration, type DeliveryDecode, type DeliveryMechanism, type DeliveryOutcome, type DeliveryRoute, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, FORM_FIELD_JSON_REASONS, type FailureKind, type FakeRequest, type FakeValues, FormFieldJsonError, type FormFieldJsonReason, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type Invite, type InviteMethod, JWT_ALGORITHMS, type JoinTarget, type JoinTargetKind, type Jwk, type JwtVerification, type LeaseAction, type LeaseDeclaration, type LeaseState, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type MimeAttachment, type MimeHeader, type MimeMessage, type MimePart, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, OIDC_JWT_SCHEME_KIND, type OidcExpectation, type OidcJwtScheme, type OidcJwtVerificationSpec, PROBLEM_SEVERITIES, PUBSUB_PUSH_REASONS, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, PubSubPushError, type PubSubPushMessage, type PubSubPushReason, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RecurrenceRule, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SETUP_ACTORS, SETUP_RENDER_REASONS, SETUP_TOKENS, SIGNED_URI_RULES, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupActor, type SetupContext, SetupRenderError, type SetupRenderReason, type SetupStep, type SetupToken, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SignedRequestLine, type SignedUriRule, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyJwtOptions, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, decodeDelivery, decodeFormFieldJson, decodePubSubPush, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isOidcJwtScheme, isOidcJwtSpec, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, normaliseSignedUri, parseInvite, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, readWithCursor, registerConnectionHost, registerTransport, render, renderSetup, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, secretKeyBytes, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifyJwt, verifyOidcDelivery, verifySharedToken, withResolvedLimit };

package/dist/index.js

@@ -163,10 +163,10 @@ var lastCallAt = /* @__PURE__ */ new Map();
 async function respectRate(channel, minIntervalMs, now = () => Date.now(), sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
   if (minIntervalMs <= 0) return { waitedMs: 0 };
   const previous = lastCallAt.get(channel);
-  const at = now();
-  const waitedMs = previous === void 0 ? 0 : Math.max(0, previous + minIntervalMs - at);
+  const at2 = now();
+  const waitedMs = previous === void 0 ? 0 : Math.max(0, previous + minIntervalMs - at2);
   if (waitedMs > 0) await sleep(waitedMs);
-  lastCallAt.set(channel, at + waitedMs);
+  lastCallAt.set(channel, at2 + waitedMs);
   return { waitedMs };
 }
 function resetRateState() {
@@ -664,6 +664,71 @@ function readString(config, key) {
   return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
 }
 
+// src/cursor-read.ts
+var CURSOR_READ_REASONS = ["cursor-missing", "cursor-expired", "cursor-overflow", "bad-page"];
+var CursorReadError = class extends Error {
+  constructor(reason, message, resyncQuery) {
+    super(message);
+    this.reason = reason;
+    this.resyncQuery = resyncQuery;
+    this.name = "CursorReadError";
+  }
+  reason;
+  resyncQuery;
+};
+async function readWithCursor(spec, cursor, call, options = {}) {
+  const refuse = (reason, message) => new CursorReadError(reason, message, options.resyncQuery);
+  const used = asCursor(cursor);
+  if (used === null) throw refuse("cursor-missing", `no stored ${spec.param}: the host seeds one before the first read`);
+  const collected = [];
+  let last;
+  let token = null;
+  let pages = 0;
+  for (; ; ) {
+    if (spec.page && pages === spec.page.maxPages) {
+      throw refuse("cursor-overflow", `more than ${spec.page.maxPages} pages since ${spec.param} ${used}`);
+    }
+    const params = { [spec.param]: used };
+    if (spec.page && token !== null) params[spec.page.param] = token;
+    try {
+      last = await call(params);
+    } catch (error) {
+      const status = error?.status;
+      if (spec.expiredStatus !== void 0 && status === spec.expiredStatus) {
+        throw refuse("cursor-expired", `${spec.param} ${used} is out of the provider's range (${status})`);
+      }
+      throw error;
+    }
+    pages++;
+    if (!spec.page) break;
+    const items = at(last, spec.page.collect);
+    if (items !== void 0 && !Array.isArray(items)) {
+      throw refuse("bad-page", `${spec.page.collect} is not a list`);
+    }
+    if (items) collected.push(...items);
+    token = asCursor(at(last, spec.page.from));
+    if (token === null) break;
+  }
+  const data = spec.page ? withList(last, spec.page.collect, collected) : last;
+  return { data, cursor: { used, next: asCursor(at(last, spec.advanceFrom)) } };
+}
+function asCursor(value) {
+  if (typeof value === "string") return value === "" ? null : value;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return null;
+}
+function at(value, path) {
+  return path.split(".").reduce(
+    (v, key) => v !== null && typeof v === "object" && !Array.isArray(v) ? v[key] : void 0,
+    value
+  );
+}
+function withList(data, path, list) {
+  const [head, ...rest] = path.split(".");
+  const base = data !== null && typeof data === "object" && !Array.isArray(data) ? data : {};
+  return { ...base, [head]: rest.length ? withList(base[head], rest.join("."), list) : list };
+}
+
 // src/drift.ts
 function resolveRef(document, node, depth = 0) {
   if (depth > 8 || node === null || typeof node !== "object") return node;
@@ -1318,32 +1383,32 @@ function base64urlBytes(segment) {
 var EXPIRES_AT_UNITS = ["rfc3339", "epoch-ms"];
 var INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
 var DEFAULT_CONTEXT = { service: "", operation: "subscription" };
-function instantMs(value, field, at) {
+function instantMs(value, field, at2) {
   if (typeof value !== "string" || !INSTANT.test(value)) {
     throw new ConnectorConfigError(
       `${field} must be an RFC 3339 instant such as "2026-09-22T00:00:00Z", got ${JSON.stringify(value)}. A provider's own shape \u2014 Google's epoch milliseconds, say \u2014 is converted by the connector, never guessed at here.`,
-      at
+      at2
     );
   }
   const ms = Date.parse(value.replace(/(\.\d{3})\d+/, "$1"));
   if (Number.isNaN(ms)) {
-    throw new ConnectorConfigError(`${field} is not a real instant: ${JSON.stringify(value)}`, at);
+    throw new ConnectorConfigError(`${field} is not a real instant: ${JSON.stringify(value)}`, at2);
   }
   return ms;
 }
-function leaseFromResponse(declaration, response, at = DEFAULT_CONTEXT) {
+function leaseFromResponse(declaration, response, at2 = DEFAULT_CONTEXT) {
   const { expiresAtFrom: path, expiresAtUnit: unit } = declaration;
   if (!EXPIRES_AT_UNITS.includes(unit)) {
     throw new ConnectorConfigError(
       `expiresAtUnit must be one of ${EXPIRES_AT_UNITS.join(" | ")}, got ${JSON.stringify(unit)}.`,
-      at
+      at2
     );
   }
   const value = readPath(response, path);
   if (value === void 0 || value === null) {
     throw new ConnectorConfigError(
       `${path} is not present in the response, so no lease can be built \u2014 a subscription with no known expiry is one nobody renews.`,
-      at
+      at2
     );
   }
   let expiresAt;
@@ -1352,7 +1417,7 @@ function leaseFromResponse(declaration, response, at = DEFAULT_CONTEXT) {
     if (!Number.isSafeInteger(ms)) {
       throw new ConnectorConfigError(
         `${path} must be epoch milliseconds as digits under "epoch-ms", got ${JSON.stringify(value)}.`,
-        at
+        at2
       );
     }
     expiresAt = new Date(ms).toISOString();
@@ -1360,14 +1425,14 @@ function leaseFromResponse(declaration, response, at = DEFAULT_CONTEXT) {
     if (typeof value !== "string" || !INSTANT.test(value)) {
       throw new ConnectorConfigError(
         `${path} must be an RFC 3339 instant under "rfc3339", got ${JSON.stringify(value)}.`,
-        at
+        at2
       );
     }
-    expiresAt = new Date(instantMs(value, path, at)).toISOString();
+    expiresAt = new Date(instantMs(value, path, at2)).toISOString();
   }
   return subscriptionLease(
     { expiresAt, renewBeforeSeconds: declaration.renewBeforeSeconds, renewOperation: declaration.renewOperation },
-    at
+    at2
   );
 }
 function readPath(value, path) {
@@ -1378,18 +1443,18 @@ function readPath(value, path) {
   }
   return current;
 }
-function subscriptionLease(input, at = DEFAULT_CONTEXT) {
-  instantMs(input.expiresAt, "expiresAt", at);
+function subscriptionLease(input, at2 = DEFAULT_CONTEXT) {
+  instantMs(input.expiresAt, "expiresAt", at2);
   if (!Number.isInteger(input.renewBeforeSeconds) || input.renewBeforeSeconds <= 0) {
     throw new ConnectorConfigError(
       `renewBeforeSeconds must be a positive whole number of seconds, got ${JSON.stringify(input.renewBeforeSeconds)}. Zero would make the lease due only at the instant it expires, which is a lease nobody renews.`,
-      at
+      at2
     );
   }
   if (typeof input.renewOperation !== "string" || input.renewOperation.trim() === "") {
     throw new ConnectorConfigError(
       "renewOperation must name the operation the host calls when the lease is due; a due lease with nothing to call is one nobody renews.",
-      at
+      at2
     );
   }
   return { expiresAt: input.expiresAt, renewBeforeSeconds: input.renewBeforeSeconds, renewOperation: input.renewOperation };
@@ -1398,10 +1463,10 @@ function leaseRenewAt(lease) {
   return new Date(instantMs(lease.expiresAt, "expiresAt", DEFAULT_CONTEXT) - lease.renewBeforeSeconds * 1e3).toISOString();
 }
 function leaseState(lease, now) {
-  const at = now instanceof Date ? now.getTime() : instantMs(now, "now", DEFAULT_CONTEXT);
+  const at2 = now instanceof Date ? now.getTime() : instantMs(now, "now", DEFAULT_CONTEXT);
   const expires = instantMs(lease.expiresAt, "expiresAt", DEFAULT_CONTEXT);
-  if (at >= expires) return "expired";
-  if (at >= expires - lease.renewBeforeSeconds * 1e3) return "due";
+  if (at2 >= expires) return "expired";
+  if (at2 >= expires - lease.renewBeforeSeconds * 1e3) return "due";
   return "active";
 }
 function leaseAction(lease, now) {
@@ -1721,8 +1786,8 @@ function splitMultipart(body, boundary) {
   if (partStart >= 0 && partStart <= body.length) children.push(body.subarray(partStart));
   return children;
 }
-function startsWith(haystack, at, needle) {
-  for (let k = 0; k < needle.length; k++) if (haystack[at + k] !== needle[k]) return false;
+function startsWith(haystack, at2, needle) {
+  for (let k = 0; k < needle.length; k++) if (haystack[at2 + k] !== needle[k]) return false;
   return true;
 }
 function parseMime(raw) {
@@ -2289,6 +2354,53 @@ function withResolvedLimit(rules, limit) {
 var CREDENTIAL_SCOPES = ["provider", "account"];
 var PROBLEM_SEVERITIES = ["block", "warn"];
 var CANONICAL_METRICS = ["like", "share", "reply", "quote", "view"];
+var SETUP_ACTORS = ["person", "agent"];
+
+// src/setup.ts
+var SETUP_TOKENS = ["appUrl", "appName", "connector"];
+var SETUP_RENDER_REASONS = ["unknown-token", "missing-context"];
+var SetupRenderError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "SetupRenderError";
+  }
+  reason;
+};
+var TOKEN = /\{\{([^{}]*)\}\}/g;
+function fill(text, context) {
+  return text.replace(TOKEN, (whole, name) => {
+    if (!SETUP_TOKENS.includes(name)) {
+      throw new SetupRenderError(
+        "unknown-token",
+        `setup step text uses ${whole}, which is not one of ${SETUP_TOKENS.map((t) => `{{${t}}}`).join(", ")}`
+      );
+    }
+    let value = context[name];
+    if (value === void 0 || value === null || value === "") {
+      throw new SetupRenderError("missing-context", `setup step text uses ${whole} and the host gave no value for ${name}`);
+    }
+    if (name === "appUrl" && value.endsWith("/")) value = value.slice(0, -1);
+    return value;
+  });
+}
+function renderSetup(steps, context) {
+  return steps.map((step) => {
+    const out = {
+      title: fill(step.title, context),
+      detail: fill(step.detail, context),
+      actor: step.actor ?? "person",
+      fields: [...step.fields ?? []]
+    };
+    if (step.url !== void 0) out.url = fill(step.url, context);
+    if (step.prompt !== void 0) out.prompt = fill(step.prompt, context);
+    if (step.done !== void 0) out.done = fill(step.done, context);
+    if (step.copy !== void 0) {
+      out.copy = step.copy.map((c) => ({ label: fill(c.label, context), value: fill(c.value, context) }));
+    }
+    return out;
+  });
+}
 
 // src/trigger.ts
 function isOidcJwtSpec(spec) {
@@ -2363,6 +2475,7 @@ export {
   CONNECTOR_API_VERSION,
   CONNECTOR_MODES,
   CREDENTIAL_SCOPES,
+  CURSOR_READ_REASONS,
   ConnectorAmbiguous,
   ConnectorApiMismatch,
   ConnectorAuthError,
@@ -2374,6 +2487,7 @@ export {
   ConnectorRequestError,
   ConnectorTransient,
   ConnectorUnreachable,
+  CursorReadError,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY,
   DELIVERY_DECODE_KINDS,
@@ -2391,8 +2505,12 @@ export {
   RENDERER_VERSION,
   REVIEW_STALE_DAYS,
   SANDBOX_KINDS,
+  SETUP_ACTORS,
+  SETUP_RENDER_REASONS,
+  SETUP_TOKENS,
   SIGNED_URI_RULES,
   SUPPORTED_CONNECTOR_API,
+  SetupRenderError,
   assertConnectorApi,
   byteRangeOf,
   callConnector,
@@ -2442,9 +2560,11 @@ export {
   probe,
   providerProblems,
   providerSandboxIsSelectable,
+  readWithCursor,
   registerConnectionHost,
   registerTransport,
   render,
+  renderSetup,
   reported,
   resetRateState,
   resolveConnection,