@particle-academy/fancy-connector-core 0.6.2 → 0.8.0

package/dist/index.d.cts

@@ -1388,6 +1388,104 @@ declare function idempotencyKeyFor(ctx: unknown, nodeId: string, options?: Idemp
  */
 declare const NO_IDEMPOTENCY_KEY_WARNING: string;
 
+/**
+ * A subscription that EXPIRES, and when the host must act on it.
+ *
+ * `DeliveryMechanism` has said since 0.1.0 that a `subscription` trigger is a
+ * webhook somebody has to renew, forever, and that if nobody does the workflow
+ * stops firing with no error anywhere. This is the value for that duty — ONE
+ * shape every expiring trigger declares, so a host runs one renewal scheduler
+ * rather than learning a loop per connector, each with its own boundary bugs.
+ *
+ * Three facts and two verbs:
+ *
+ * - `expiresAt` — the provider's expiry, as an RFC 3339 instant. Google Calendar
+ *   hands back `expiration` as epoch MILLISECONDS in a string and Microsoft
+ *   Graph hands back `expirationDateTime` as ISO 8601; the CONNECTOR converts on
+ *   the way in, and this module refuses anything that is not an instant rather
+ *   than guessing units.
+ * - `renewBeforeSeconds` — the connector's margin. Positive, because zero would
+ *   make `due` unreachable (the moment it applied, `expired` would win) — a
+ *   lease nobody ever renews, declared in a way nothing would report.
+ * - `renewOperation` — the operation the host calls when the lease is due. For
+ *   Graph that is a renew; for a Google Calendar channel, which cannot be
+ *   renewed, it is the create again (the connector stops the old channel
+ *   itself). The lease says WHEN; the connector says WHAT.
+ *
+ * - `leaseState` — where the lease IS: `active`, `due` (inclusive at renewAt),
+ *   `expired` (inclusive at expiresAt, and it wins over `due`: a lease that has
+ *   just expired cannot be renewed).
+ * - `leaseAction` — what the host DOES: `none`, `renew`, or `resync`. A missed
+ *   lease is never a quiet re-create: notifications during the gap are gone, so
+ *   the host must re-list (sync token or full) AND re-subscribe.
+ *
+ * The boundaries are DECIDED, not measured, and they are pinned in
+ * fancy-conformance's `shared/subscription-lease` suite, which drives the PHP
+ * twin too (`tests/subscription-lease.test.ts` and its Pest mirror).
+ */
+
+type SubscriptionLease = {
+    /** The provider's expiry, an RFC 3339 instant. */
+    expiresAt: string;
+    /** How early the host renews, in seconds. Positive. */
+    renewBeforeSeconds: number;
+    /** The operation the host calls when the lease is due. */
+    renewOperation: string;
+};
+type LeaseState = "active" | "due" | "expired";
+type LeaseAction = "none" | "renew" | "resync";
+/**
+ * How a provider spells its expiry. Two, because two providers: Google
+ * Calendar's channel `expiration` is epoch MILLISECONDS (as a JSON string, and
+ * a number is accepted too); Microsoft Graph's `expirationDateTime` is ISO
+ * 8601 with a seven-digit fraction. A unit no shipped provider spells is not
+ * here — a vocabulary with no provider is a claim that outruns the code.
+ *
+ * Data as well as a type: a host validates a definition at the JSON boundary,
+ * where `tsc` cannot see.
+ */
+declare const EXPIRES_AT_UNITS: readonly ["rfc3339", "epoch-ms"];
+type ExpiresAtUnit = (typeof EXPIRES_AT_UNITS)[number];
+/**
+ * What a subscription trigger DECLARES about its lease, so a host can build
+ * the value from the provider's create (or renew) response without knowing
+ * the provider.
+ */
+type LeaseDeclaration = {
+    /** Dotted path to the expiry in the create/renew response, e.g. `expiration` or `channel.expiration`. */
+    expiresAtFrom: string;
+    expiresAtUnit: ExpiresAtUnit;
+    /** How early the host renews, in seconds. Positive. */
+    renewBeforeSeconds: number;
+    /** The operation the host calls when the lease is due. */
+    renewOperation: string;
+};
+/**
+ * Build the lease from the provider's create (or renew) response, by
+ * declaration. The declared unit is never guessed around: digits under
+ * `rfc3339`, or an instant under `epoch-ms`, are refused — a lease built from
+ * a misread expiry is one that expires unannounced.
+ *
+ * The expiry is stored as an RFC 3339 instant in UTC at millisecond
+ * precision; the lease's own refusals (margin, operation) still apply.
+ */
+declare function leaseFromResponse(declaration: LeaseDeclaration, response: unknown, at?: ConnectorErrorContext): SubscriptionLease;
+/**
+ * Validate a declaration and return the lease — a plain value a host stores
+ * beside the trigger and hands back to `leaseState` / `leaseAction` later.
+ */
+declare function subscriptionLease(input: {
+    expiresAt: string;
+    renewBeforeSeconds: number;
+    renewOperation: string;
+}, at?: ConnectorErrorContext): SubscriptionLease;
+/** The instant the lease becomes due: `expiresAt - renewBeforeSeconds`. */
+declare function leaseRenewAt(lease: SubscriptionLease): string;
+/** Where the lease is at `now`. Both boundaries are inclusive; `expired` wins. */
+declare function leaseState(lease: SubscriptionLease, now: string | Date): LeaseState;
+/** What the host does about the lease at `now`. */
+declare function leaseAction(lease: SubscriptionLease, now: string | Date): LeaseAction;
+
 /**
  * Measuring and slicing text the way providers actually measure and slice it.
  *
@@ -2058,6 +2156,58 @@ declare function providerProblems(provider: ProviderAdapter): string[];
 /** True when a provider's declared sandbox can actually be selected at run time. */
 declare function providerSandboxIsSelectable(provider: ProviderAdapter): boolean;
 
+/**
+ * Raw MIME in, headers / parts / attachments out — the payload TRANSFORM an
+ * inbound-email trigger declares.
+ *
+ * Written from scratch (the owner: no third-party code), as ONE implementation
+ * in two runtimes — `php/src/Mime.php` is the twin — and held to the authored
+ * corpus under `fixtures/mime/`, which both must reproduce byte for byte.
+ * `fixtures/mime/README.md` lists every decision a case pins; the ones that
+ * are easy to get differently in two languages are restated here:
+ *
+ * - Header lines are read as Latin-1 (one byte, one char), unfolded with a
+ *   single space, names lowercased, values RFC 2047-decoded (B and Q; adjacent
+ *   encoded-words join without the whitespace between them).
+ * - The line break before a boundary delimiter belongs to the DELIMITER.
+ * - `size` is the transfer-decoded byte length, before any charset conversion.
+ * - A text part comes back as UTF-8 with the message's own line endings. A
+ *   charset this module does not decode (anything but utf-8, us-ascii,
+ *   iso-8859-1, iso-8859-15, windows-1252) leaves the part with no text.
+ * - Every non-text leaf is an attachment, as is a text leaf declared
+ *   `attachment`; attachments carry their bytes as base64. `filename*` (RFC
+ *   2231) wins over `filename`, which wins over Content-Type's `name`.
+ * - `messageId` is the header verbatim; `contentId` has its angle brackets
+ *   stripped, because `cid:` references omit them.
+ */
+type MimeHeader = {
+    name: string;
+    value: string;
+};
+type MimePart = {
+    index: number;
+    contentType: string;
+    charset: string | null;
+    disposition: "inline" | "attachment" | null;
+    filename: string | null;
+    contentId: string | null;
+    size: number;
+    headers: MimeHeader[];
+};
+type MimeAttachment = MimePart & {
+    content: string;
+};
+type MimeMessage = {
+    headers: MimeHeader[];
+    subject: string | null;
+    messageId: string | null;
+    text: string | null;
+    html: string | null;
+    parts: MimePart[];
+    attachments: MimeAttachment[];
+};
+declare function parseMime(raw: Uint8Array | string): MimeMessage;
+
 /**
  * Dry-verify — proving the transport with a credential that cannot work.
  *
@@ -2222,6 +2372,58 @@ declare function hmac(secret: string, payload: string, algorithm: HmacScheme["al
  * attacker nothing they could not compute.
  */
 declare function constantTimeEquals(a: string, b: string): boolean;
+/**
+ * A delivery verified by a token the provider ECHOES rather than a signature
+ * it computes.
+ *
+ * Google Calendar sends the channel's `token` back in `X-Goog-Channel-Token`
+ * on every notification — with an EMPTY body, so there is nothing to sign.
+ * Microsoft Graph sends `clientState` inside every item of the notification's
+ * `value` array. Same refusal-by-default as HMAC, same result shape, and a
+ * constant-time comparison: a token is a secret, and `===` leaks which prefix
+ * was right.
+ *
+ * A body `path` is dotted; a segment ending in `[]` means EVERY element of that
+ * array, all of which must match — one wrong item refuses the whole delivery.
+ */
+type SharedTokenScheme = {
+    kind: "shared-token";
+    in: "header";
+    name: string;
+} | {
+    kind: "shared-token";
+    in: "body";
+    path: string;
+};
+declare function isSharedTokenScheme(scheme: HmacScheme | SharedTokenScheme): scheme is SharedTokenScheme;
+declare function verifySharedToken(options: {
+    raw: string;
+    headers: Record<string, string | string[] | undefined>;
+    secret: string | undefined;
+    scheme: SharedTokenScheme;
+}): WebhookVerification;
+/**
+ * A challenge the provider makes BEFORE it will deliver anything, answered by
+ * echoing a query parameter as plain text. Microsoft Graph POSTs
+ * `?validationToken=…` to the notification URL when a subscription is created
+ * and refuses to create it unless the token comes back, decoded, as
+ * `text/plain` within ten seconds.
+ *
+ * Declared as data on the trigger so a host can answer it in its own routing
+ * layer; `handshakeResponse` is the pure half — what to send, or `undefined`
+ * when the request is not a challenge at all.
+ */
+type ChallengeHandshake = {
+    kind: "echo-query";
+    /** The query parameter carrying the challenge. */
+    param: string;
+    contentType?: "text/plain";
+};
+declare function handshakeResponse(handshake: ChallengeHandshake | undefined, query: Record<string, string | string[] | undefined>): {
+    status: 200;
+    contentType: string;
+    body: string;
+} | undefined;
 /**
  * Pull one header case-insensitively.
  *
@@ -2272,6 +2474,13 @@ type TriggerDescriptor = {
     setup: string;
     /** For `subscription`: how long the provider keeps it alive, in seconds. */
     subscriptionTtl?: number;
+    /**
+     * For `subscription`: where the provider's expiry sits in the create/renew
+     * response and how it is spelled, so a host builds the `SubscriptionLease`
+     * with `leaseFromResponse` and runs ONE renewal scheduler for every
+     * expiring trigger.
+     */
+    lease?: LeaseDeclaration;
     /** For `webhook` / `subscription`: how a delivery is authenticated. */
     verification?: WebhookVerificationSpec;
     /** For `poll`: the provider's smallest sane interval, in seconds. */
@@ -2279,7 +2488,8 @@ type TriggerDescriptor = {
     /** A faked sample event, so the node is runnable before any of the above. */
     faker: ConnectorFaker;
 };
-type WebhookVerificationSpec = {
+/** The provider SIGNS each delivery. */
+type HmacVerificationSpec = {
     /** Header carrying the signature. */
     signatureHeader: string;
     /** Header carrying the timestamp, when the scheme signs one. */
@@ -2293,7 +2503,20 @@ type WebhookVerificationSpec = {
         signature?: string;
         timestamp?: string;
     };
+    /** A challenge the provider makes before it will deliver anything. */
+    handshake?: ChallengeHandshake;
+};
+/**
+ * The provider ECHOES a token the subscriber chose. Google Calendar's channel
+ * token, Graph's `clientState`. See `SharedTokenScheme`.
+ */
+type SharedTokenVerificationSpec = {
+    scheme: SharedTokenScheme;
+    /** A challenge the provider makes before it will deliver anything. */
+    handshake?: ChallengeHandshake;
 };
+type WebhookVerificationSpec = HmacVerificationSpec | SharedTokenVerificationSpec;
+declare function isSharedTokenSpec(spec: WebhookVerificationSpec): spec is SharedTokenVerificationSpec;
 type InboundDelivery = {
     /** The body EXACTLY as received. Not re-serialised. See `webhook.ts`. */
     raw: string;
@@ -2323,4 +2546,4 @@ declare function verifyDelivery(trigger: TriggerDescriptor, delivery: InboundDel
  */
 declare function triggerEvent(trigger: TriggerDescriptor, connection: ResolvedConnection, injected: unknown, config: Record<string, unknown>): unknown;
 
-export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, 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 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, type DeliveryDeclaration, type DeliveryMechanism, type DeliveryOutcome, type DriftFinding, type DriftReport, FAKE_EPOCH, type FailureKind, type FakeRequest, type FakeValues, type HmacScheme, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, PROBLEM_SEVERITIES, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SpecSource, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isUnconditionallyRetryable, linkRanges, measure, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, withResolvedLimit };
+export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, 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, type DeliveryDeclaration, type DeliveryMechanism, type DeliveryOutcome, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, type FailureKind, type FakeRequest, type FakeValues, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, 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, PROBLEM_SEVERITIES, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifySharedToken, withResolvedLimit };

package/dist/index.d.ts

@@ -1388,6 +1388,104 @@ declare function idempotencyKeyFor(ctx: unknown, nodeId: string, options?: Idemp
  */
 declare const NO_IDEMPOTENCY_KEY_WARNING: string;
 
+/**
+ * A subscription that EXPIRES, and when the host must act on it.
+ *
+ * `DeliveryMechanism` has said since 0.1.0 that a `subscription` trigger is a
+ * webhook somebody has to renew, forever, and that if nobody does the workflow
+ * stops firing with no error anywhere. This is the value for that duty — ONE
+ * shape every expiring trigger declares, so a host runs one renewal scheduler
+ * rather than learning a loop per connector, each with its own boundary bugs.
+ *
+ * Three facts and two verbs:
+ *
+ * - `expiresAt` — the provider's expiry, as an RFC 3339 instant. Google Calendar
+ *   hands back `expiration` as epoch MILLISECONDS in a string and Microsoft
+ *   Graph hands back `expirationDateTime` as ISO 8601; the CONNECTOR converts on
+ *   the way in, and this module refuses anything that is not an instant rather
+ *   than guessing units.
+ * - `renewBeforeSeconds` — the connector's margin. Positive, because zero would
+ *   make `due` unreachable (the moment it applied, `expired` would win) — a
+ *   lease nobody ever renews, declared in a way nothing would report.
+ * - `renewOperation` — the operation the host calls when the lease is due. For
+ *   Graph that is a renew; for a Google Calendar channel, which cannot be
+ *   renewed, it is the create again (the connector stops the old channel
+ *   itself). The lease says WHEN; the connector says WHAT.
+ *
+ * - `leaseState` — where the lease IS: `active`, `due` (inclusive at renewAt),
+ *   `expired` (inclusive at expiresAt, and it wins over `due`: a lease that has
+ *   just expired cannot be renewed).
+ * - `leaseAction` — what the host DOES: `none`, `renew`, or `resync`. A missed
+ *   lease is never a quiet re-create: notifications during the gap are gone, so
+ *   the host must re-list (sync token or full) AND re-subscribe.
+ *
+ * The boundaries are DECIDED, not measured, and they are pinned in
+ * fancy-conformance's `shared/subscription-lease` suite, which drives the PHP
+ * twin too (`tests/subscription-lease.test.ts` and its Pest mirror).
+ */
+
+type SubscriptionLease = {
+    /** The provider's expiry, an RFC 3339 instant. */
+    expiresAt: string;
+    /** How early the host renews, in seconds. Positive. */
+    renewBeforeSeconds: number;
+    /** The operation the host calls when the lease is due. */
+    renewOperation: string;
+};
+type LeaseState = "active" | "due" | "expired";
+type LeaseAction = "none" | "renew" | "resync";
+/**
+ * How a provider spells its expiry. Two, because two providers: Google
+ * Calendar's channel `expiration` is epoch MILLISECONDS (as a JSON string, and
+ * a number is accepted too); Microsoft Graph's `expirationDateTime` is ISO
+ * 8601 with a seven-digit fraction. A unit no shipped provider spells is not
+ * here — a vocabulary with no provider is a claim that outruns the code.
+ *
+ * Data as well as a type: a host validates a definition at the JSON boundary,
+ * where `tsc` cannot see.
+ */
+declare const EXPIRES_AT_UNITS: readonly ["rfc3339", "epoch-ms"];
+type ExpiresAtUnit = (typeof EXPIRES_AT_UNITS)[number];
+/**
+ * What a subscription trigger DECLARES about its lease, so a host can build
+ * the value from the provider's create (or renew) response without knowing
+ * the provider.
+ */
+type LeaseDeclaration = {
+    /** Dotted path to the expiry in the create/renew response, e.g. `expiration` or `channel.expiration`. */
+    expiresAtFrom: string;
+    expiresAtUnit: ExpiresAtUnit;
+    /** How early the host renews, in seconds. Positive. */
+    renewBeforeSeconds: number;
+    /** The operation the host calls when the lease is due. */
+    renewOperation: string;
+};
+/**
+ * Build the lease from the provider's create (or renew) response, by
+ * declaration. The declared unit is never guessed around: digits under
+ * `rfc3339`, or an instant under `epoch-ms`, are refused — a lease built from
+ * a misread expiry is one that expires unannounced.
+ *
+ * The expiry is stored as an RFC 3339 instant in UTC at millisecond
+ * precision; the lease's own refusals (margin, operation) still apply.
+ */
+declare function leaseFromResponse(declaration: LeaseDeclaration, response: unknown, at?: ConnectorErrorContext): SubscriptionLease;
+/**
+ * Validate a declaration and return the lease — a plain value a host stores
+ * beside the trigger and hands back to `leaseState` / `leaseAction` later.
+ */
+declare function subscriptionLease(input: {
+    expiresAt: string;
+    renewBeforeSeconds: number;
+    renewOperation: string;
+}, at?: ConnectorErrorContext): SubscriptionLease;
+/** The instant the lease becomes due: `expiresAt - renewBeforeSeconds`. */
+declare function leaseRenewAt(lease: SubscriptionLease): string;
+/** Where the lease is at `now`. Both boundaries are inclusive; `expired` wins. */
+declare function leaseState(lease: SubscriptionLease, now: string | Date): LeaseState;
+/** What the host does about the lease at `now`. */
+declare function leaseAction(lease: SubscriptionLease, now: string | Date): LeaseAction;
+
 /**
  * Measuring and slicing text the way providers actually measure and slice it.
  *
@@ -2058,6 +2156,58 @@ declare function providerProblems(provider: ProviderAdapter): string[];
 /** True when a provider's declared sandbox can actually be selected at run time. */
 declare function providerSandboxIsSelectable(provider: ProviderAdapter): boolean;
 
+/**
+ * Raw MIME in, headers / parts / attachments out — the payload TRANSFORM an
+ * inbound-email trigger declares.
+ *
+ * Written from scratch (the owner: no third-party code), as ONE implementation
+ * in two runtimes — `php/src/Mime.php` is the twin — and held to the authored
+ * corpus under `fixtures/mime/`, which both must reproduce byte for byte.
+ * `fixtures/mime/README.md` lists every decision a case pins; the ones that
+ * are easy to get differently in two languages are restated here:
+ *
+ * - Header lines are read as Latin-1 (one byte, one char), unfolded with a
+ *   single space, names lowercased, values RFC 2047-decoded (B and Q; adjacent
+ *   encoded-words join without the whitespace between them).
+ * - The line break before a boundary delimiter belongs to the DELIMITER.
+ * - `size` is the transfer-decoded byte length, before any charset conversion.
+ * - A text part comes back as UTF-8 with the message's own line endings. A
+ *   charset this module does not decode (anything but utf-8, us-ascii,
+ *   iso-8859-1, iso-8859-15, windows-1252) leaves the part with no text.
+ * - Every non-text leaf is an attachment, as is a text leaf declared
+ *   `attachment`; attachments carry their bytes as base64. `filename*` (RFC
+ *   2231) wins over `filename`, which wins over Content-Type's `name`.
+ * - `messageId` is the header verbatim; `contentId` has its angle brackets
+ *   stripped, because `cid:` references omit them.
+ */
+type MimeHeader = {
+    name: string;
+    value: string;
+};
+type MimePart = {
+    index: number;
+    contentType: string;
+    charset: string | null;
+    disposition: "inline" | "attachment" | null;
+    filename: string | null;
+    contentId: string | null;
+    size: number;
+    headers: MimeHeader[];
+};
+type MimeAttachment = MimePart & {
+    content: string;
+};
+type MimeMessage = {
+    headers: MimeHeader[];
+    subject: string | null;
+    messageId: string | null;
+    text: string | null;
+    html: string | null;
+    parts: MimePart[];
+    attachments: MimeAttachment[];
+};
+declare function parseMime(raw: Uint8Array | string): MimeMessage;
+
 /**
  * Dry-verify — proving the transport with a credential that cannot work.
  *
@@ -2222,6 +2372,58 @@ declare function hmac(secret: string, payload: string, algorithm: HmacScheme["al
  * attacker nothing they could not compute.
  */
 declare function constantTimeEquals(a: string, b: string): boolean;
+/**
+ * A delivery verified by a token the provider ECHOES rather than a signature
+ * it computes.
+ *
+ * Google Calendar sends the channel's `token` back in `X-Goog-Channel-Token`
+ * on every notification — with an EMPTY body, so there is nothing to sign.
+ * Microsoft Graph sends `clientState` inside every item of the notification's
+ * `value` array. Same refusal-by-default as HMAC, same result shape, and a
+ * constant-time comparison: a token is a secret, and `===` leaks which prefix
+ * was right.
+ *
+ * A body `path` is dotted; a segment ending in `[]` means EVERY element of that
+ * array, all of which must match — one wrong item refuses the whole delivery.
+ */
+type SharedTokenScheme = {
+    kind: "shared-token";
+    in: "header";
+    name: string;
+} | {
+    kind: "shared-token";
+    in: "body";
+    path: string;
+};
+declare function isSharedTokenScheme(scheme: HmacScheme | SharedTokenScheme): scheme is SharedTokenScheme;
+declare function verifySharedToken(options: {
+    raw: string;
+    headers: Record<string, string | string[] | undefined>;
+    secret: string | undefined;
+    scheme: SharedTokenScheme;
+}): WebhookVerification;
+/**
+ * A challenge the provider makes BEFORE it will deliver anything, answered by
+ * echoing a query parameter as plain text. Microsoft Graph POSTs
+ * `?validationToken=…` to the notification URL when a subscription is created
+ * and refuses to create it unless the token comes back, decoded, as
+ * `text/plain` within ten seconds.
+ *
+ * Declared as data on the trigger so a host can answer it in its own routing
+ * layer; `handshakeResponse` is the pure half — what to send, or `undefined`
+ * when the request is not a challenge at all.
+ */
+type ChallengeHandshake = {
+    kind: "echo-query";
+    /** The query parameter carrying the challenge. */
+    param: string;
+    contentType?: "text/plain";
+};
+declare function handshakeResponse(handshake: ChallengeHandshake | undefined, query: Record<string, string | string[] | undefined>): {
+    status: 200;
+    contentType: string;
+    body: string;
+} | undefined;
 /**
  * Pull one header case-insensitively.
  *
@@ -2272,6 +2474,13 @@ type TriggerDescriptor = {
     setup: string;
     /** For `subscription`: how long the provider keeps it alive, in seconds. */
     subscriptionTtl?: number;
+    /**
+     * For `subscription`: where the provider's expiry sits in the create/renew
+     * response and how it is spelled, so a host builds the `SubscriptionLease`
+     * with `leaseFromResponse` and runs ONE renewal scheduler for every
+     * expiring trigger.
+     */
+    lease?: LeaseDeclaration;
     /** For `webhook` / `subscription`: how a delivery is authenticated. */
     verification?: WebhookVerificationSpec;
     /** For `poll`: the provider's smallest sane interval, in seconds. */
@@ -2279,7 +2488,8 @@ type TriggerDescriptor = {
     /** A faked sample event, so the node is runnable before any of the above. */
     faker: ConnectorFaker;
 };
-type WebhookVerificationSpec = {
+/** The provider SIGNS each delivery. */
+type HmacVerificationSpec = {
     /** Header carrying the signature. */
     signatureHeader: string;
     /** Header carrying the timestamp, when the scheme signs one. */
@@ -2293,7 +2503,20 @@ type WebhookVerificationSpec = {
         signature?: string;
         timestamp?: string;
     };
+    /** A challenge the provider makes before it will deliver anything. */
+    handshake?: ChallengeHandshake;
+};
+/**
+ * The provider ECHOES a token the subscriber chose. Google Calendar's channel
+ * token, Graph's `clientState`. See `SharedTokenScheme`.
+ */
+type SharedTokenVerificationSpec = {
+    scheme: SharedTokenScheme;
+    /** A challenge the provider makes before it will deliver anything. */
+    handshake?: ChallengeHandshake;
 };
+type WebhookVerificationSpec = HmacVerificationSpec | SharedTokenVerificationSpec;
+declare function isSharedTokenSpec(spec: WebhookVerificationSpec): spec is SharedTokenVerificationSpec;
 type InboundDelivery = {
     /** The body EXACTLY as received. Not re-serialised. See `webhook.ts`. */
     raw: string;
@@ -2323,4 +2546,4 @@ declare function verifyDelivery(trigger: TriggerDescriptor, delivery: InboundDel
  */
 declare function triggerEvent(trigger: TriggerDescriptor, connection: ResolvedConnection, injected: unknown, config: Record<string, unknown>): unknown;
 
-export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, 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 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, type DeliveryDeclaration, type DeliveryMechanism, type DeliveryOutcome, type DriftFinding, type DriftReport, FAKE_EPOCH, type FailureKind, type FakeRequest, type FakeValues, type HmacScheme, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, PROBLEM_SEVERITIES, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SpecSource, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isUnconditionallyRetryable, linkRanges, measure, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, withResolvedLimit };
+export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, 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, type DeliveryDeclaration, type DeliveryMechanism, type DeliveryOutcome, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, type FailureKind, type FakeRequest, type FakeValues, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, 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, PROBLEM_SEVERITIES, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifySharedToken, withResolvedLimit };