@particle-academy/fancy-connector-core 0.6.1 → 0.7.0

package/dist/index.d.cts

@@ -1388,6 +1388,67 @@ 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
+ * `fixtures/subscription-lease/cases.json`, which the PHP twin reads too.
+ */
+
+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";
+/**
+ * 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 +2119,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.
  *
@@ -2323,4 +2436,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 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, type LeaseAction, 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 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, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isUnconditionallyRetryable, leaseAction, 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, withResolvedLimit };

package/dist/index.d.ts

@@ -1388,6 +1388,67 @@ 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
+ * `fixtures/subscription-lease/cases.json`, which the PHP twin reads too.
+ */
+
+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";
+/**
+ * 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 +2119,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.
  *
@@ -2323,4 +2436,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 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, type LeaseAction, 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 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, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isUnconditionallyRetryable, leaseAction, 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, withResolvedLimit };

package/dist/index.js

@@ -34,7 +34,7 @@ function assertConnectorApi(connectorId, declared) {
   if (SUPPORTED_CONNECTOR_API.includes(declared)) return;
   const supported = SUPPORTED_CONNECTOR_API.join(", ");
   throw new ConnectorApiMismatch(
-    declared > CONNECTOR_API_VERSION ? `"${connectorId}" was written against connector API ${declared}, and this core implements ${supported}. The CONNECTOR is newer: upgrade @particle-academy/fancy-connector-core. Vendoring a connector ahead of the core it needs is the one direction that cannot be made to work by trying.` : `"${connectorId}" was written against connector API ${declared}, which is older than anything this core still runs (${supported}). The CONNECTOR is behind: re-vendor it \u2014 \`npx fancy-cli@latest add connector ${connectorId}\` \u2014 which fetches the copy written for this core. Nothing is adapted automatically, because guessing what a two-version-old connector meant is how a connector quietly starts doing something else.`,
+    declared > CONNECTOR_API_VERSION ? `"${connectorId}" was written against connector API ${declared}, and this core implements ${supported}. The CONNECTOR is newer: upgrade @particle-academy/fancy-connector-core. Vendoring a connector ahead of the core it needs is the one direction that cannot be made to work by trying.` : `"${connectorId}" was written against connector API ${declared}, which is older than anything this core still runs (${supported}). The CONNECTOR is behind: move it to a release written for this core \u2014 upgrade its package (@particle-academy/${connectorId}-js, particle-academy/${connectorId}-php), or regenerate a vendored copy from that release; its CHANGELOG names the connector API each release targets. Nothing is adapted automatically, because guessing what a two-version-old connector meant is how a connector quietly starts doing something else.`,
     connectorId,
     declared
   );
@@ -595,21 +595,21 @@ async function prepare(service, connection, options) {
 }
 function encodeForm(form) {
   const pairs = [];
-  const walk = (prefix, value) => {
+  const walk2 = (prefix, value) => {
     if (value === void 0 || value === null) return;
     if (Array.isArray(value)) {
-      value.forEach((item, index) => walk(`${prefix}[${index}]`, item));
+      value.forEach((item, index) => walk2(`${prefix}[${index}]`, item));
       return;
     }
     if (typeof value === "object") {
       for (const [key, nested] of Object.entries(value)) {
-        walk(prefix === "" ? key : `${prefix}[${key}]`, nested);
+        walk2(prefix === "" ? key : `${prefix}[${key}]`, nested);
       }
       return;
     }
     pairs.push(`${encodeURIComponent(prefix)}=${encodeURIComponent(String(value))}`);
   };
-  walk("", form);
+  walk2("", form);
   return pairs.join("&");
 }
 var fetchTransport = async (request) => {
@@ -913,6 +913,59 @@ function fnv1a(value) {
   return hash.toString(16).padStart(8, "0");
 }
 
+// src/lease.ts
+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) {
+  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
+    );
+  }
+  const ms = Date.parse(value);
+  if (Number.isNaN(ms)) {
+    throw new ConnectorConfigError(`${field} is not a real instant: ${JSON.stringify(value)}`, at);
+  }
+  return ms;
+}
+function subscriptionLease(input, at = DEFAULT_CONTEXT) {
+  instantMs(input.expiresAt, "expiresAt", at);
+  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
+    );
+  }
+  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
+    );
+  }
+  return { expiresAt: input.expiresAt, renewBeforeSeconds: input.renewBeforeSeconds, renewOperation: input.renewOperation };
+}
+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 expires = instantMs(lease.expiresAt, "expiresAt", DEFAULT_CONTEXT);
+  if (at >= expires) return "expired";
+  if (at >= expires - lease.renewBeforeSeconds * 1e3) return "due";
+  return "active";
+}
+function leaseAction(lease, now) {
+  switch (leaseState(lease, now)) {
+    case "active":
+      return "none";
+    case "due":
+      return "renew";
+    case "expired":
+      return "resync";
+  }
+}
+
 // src/metrics.ts
 function compareShape(connectorId, declared, produced) {
   const declaredKeys = new Set((declared ?? []).map((metric) => metric.key));
@@ -1007,6 +1060,245 @@ function providerSandboxIsSelectable(provider) {
   return sandboxIsSelectable(provider.sandbox);
 }
 
+// src/mime.ts
+var CR = 13;
+var LF = 10;
+function latin1(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return s;
+}
+function bytesOfLatin1(s) {
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i) & 255;
+  return out;
+}
+function splitEntity(bytes) {
+  for (let i = 0; i < bytes.length; i++) {
+    if (bytes[i] === LF) {
+      if (bytes[i + 1] === LF) return [i, i + 2];
+      if (bytes[i + 1] === CR && bytes[i + 2] === LF) return [i, i + 3];
+    }
+  }
+  return [bytes.length, bytes.length];
+}
+function parseHeaders(block) {
+  const lines = block.split(/\r?\n/);
+  const unfolded = [];
+  for (const line of lines) {
+    if (line === "") continue;
+    if ((line.startsWith(" ") || line.startsWith("	")) && unfolded.length > 0) {
+      unfolded[unfolded.length - 1] += " " + line.trim();
+    } else {
+      unfolded.push(line);
+    }
+  }
+  const headers = [];
+  for (const line of unfolded) {
+    const colon = line.indexOf(":");
+    if (colon <= 0) continue;
+    headers.push({ name: line.slice(0, colon).trim().toLowerCase(), value: decodeWords(line.slice(colon + 1).trim()) });
+  }
+  return headers;
+}
+function header(headers, name) {
+  return headers.find((h) => h.name === name)?.value ?? null;
+}
+var ENCODED_WORD = /=\?([^?\s]+)\?([BbQq])\?([^?\s]*)\?=/g;
+function decodeWords(value) {
+  const joined = value.replace(/(\?=)[ \t\r\n]+(=\?)/g, "$1$2");
+  return joined.replace(ENCODED_WORD, (whole, charset, encoding, text) => {
+    const bytes = encoding.toUpperCase() === "B" ? base64Bytes(text) : bytesOfLatin1(text.replace(/_/g, " ").replace(/=([0-9A-Fa-f]{2})/g, (_m, h) => String.fromCharCode(parseInt(h, 16))));
+    const decoded = decodeCharset(bytes, charset);
+    return decoded ?? whole;
+  });
+}
+function parseParams(value) {
+  const [head, ...rest] = value.split(";");
+  const params = {};
+  const continued = {};
+  for (const piece of rest) {
+    const eq = piece.indexOf("=");
+    if (eq < 0) continue;
+    let key = piece.slice(0, eq).trim().toLowerCase();
+    let raw = piece.slice(eq + 1).trim();
+    if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) raw = raw.slice(1, -1).replace(/\\(.)/g, "$1");
+    const segment = /^(.+?)\*(\d+)(\*)?$/.exec(key);
+    if (segment) {
+      const [, base, n, star] = segment;
+      (continued[base] ??= [])[Number(n)] = star ? decode2231(raw, Number(n) === 0) : raw;
+      continue;
+    }
+    if (key.endsWith("*")) {
+      key = key.slice(0, -1);
+      params[key] = decode2231(raw, true);
+      continue;
+    }
+    params[key] ??= raw;
+  }
+  for (const [base, parts] of Object.entries(continued)) params[base] = parts.join("");
+  return { main: (head ?? "").trim().toLowerCase(), params };
+}
+var pendingCharset2231 = "utf-8";
+function decode2231(raw, first) {
+  let text = raw;
+  if (first) {
+    const m = /^([^']*)'[^']*'(.*)$/s.exec(raw);
+    if (m) {
+      pendingCharset2231 = m[1] || "utf-8";
+      text = m[2];
+    }
+  }
+  const bytes = bytesOfLatin1(text.replace(/%([0-9A-Fa-f]{2})/g, (_m, h) => String.fromCharCode(parseInt(h, 16))));
+  return decodeCharset(bytes, pendingCharset2231) ?? text;
+}
+function base64Bytes(text) {
+  return new Uint8Array(Buffer.from(text.replace(/[^A-Za-z0-9+/=]/g, ""), "base64"));
+}
+function quotedPrintableBytes(bytes) {
+  const out = [];
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    if (b !== 61) {
+      out.push(b);
+      continue;
+    }
+    const a = bytes[i + 1];
+    const c = bytes[i + 2];
+    if (a === LF) {
+      i += 1;
+      continue;
+    }
+    if (a === CR && c === LF) {
+      i += 2;
+      continue;
+    }
+    if (a !== void 0 && c !== void 0 && isHex(a) && isHex(c)) {
+      out.push(parseInt(String.fromCharCode(a, c), 16));
+      i += 2;
+      continue;
+    }
+    out.push(b);
+  }
+  return new Uint8Array(out);
+}
+function isHex(b) {
+  return b >= 48 && b <= 57 || b >= 65 && b <= 70 || b >= 97 && b <= 102;
+}
+function transferDecode(body, encoding) {
+  switch ((encoding ?? "7bit").trim().toLowerCase()) {
+    case "base64":
+      return base64Bytes(latin1(body));
+    case "quoted-printable":
+      return quotedPrintableBytes(body);
+    default:
+      return body;
+  }
+}
+function decodeCharset(bytes, charset) {
+  switch (charset.trim().toLowerCase()) {
+    case "utf-8":
+    case "utf8":
+      return new TextDecoder("utf-8").decode(bytes);
+    case "us-ascii":
+    case "ascii":
+    case "iso-8859-1":
+    case "latin1":
+      return Buffer.from(bytes).toString("latin1");
+    case "windows-1252":
+    case "cp1252":
+      return new TextDecoder("windows-1252").decode(bytes);
+    case "iso-8859-15":
+    case "latin9":
+      return new TextDecoder("iso-8859-15").decode(bytes);
+    default:
+      return null;
+  }
+}
+function walk(bytes, entityHeaders, acc) {
+  const [headerEnd, bodyStart] = splitEntity(bytes);
+  const headers = entityHeaders ?? parseHeaders(latin1(bytes.subarray(0, headerEnd)));
+  const body = bytes.subarray(entityHeaders ? 0 : bodyStart);
+  const type = parseParams(header(headers, "content-type") ?? "text/plain");
+  if (type.main.startsWith("multipart/") && type.params.boundary) {
+    for (const child of splitMultipart(body, type.params.boundary)) walk(child, null, acc);
+    return;
+  }
+  const disposition = parseParams(header(headers, "content-disposition") ?? "");
+  const decoded = transferDecode(body, header(headers, "content-transfer-encoding"));
+  const declaredDisposition = disposition.main === "attachment" || disposition.main === "inline" ? disposition.main : null;
+  const filename = disposition.params.filename ?? type.params.name ?? null;
+  const contentId = header(headers, "content-id")?.replace(/^<|>$/g, "") ?? null;
+  const isText = type.main.startsWith("text/");
+  const isAttachment = declaredDisposition === "attachment" || !isText;
+  const part = {
+    index: acc.parts.length,
+    contentType: type.main,
+    charset: type.params.charset?.toLowerCase() ?? null,
+    disposition: declaredDisposition,
+    filename,
+    contentId,
+    size: decoded.length,
+    headers
+  };
+  acc.parts.push(part);
+  if (isAttachment) {
+    acc.attachments.push({ ...part, content: Buffer.from(decoded).toString("base64") });
+    return;
+  }
+  const text = decodeCharset(decoded, type.params.charset ?? "utf-8");
+  if (text === null) return;
+  if (type.main === "text/plain" && acc.text === null) acc.text = text;
+  if (type.main === "text/html" && acc.html === null) acc.html = text;
+}
+function splitMultipart(body, boundary) {
+  const delimiter = bytesOfLatin1(`--${boundary}`);
+  const children = [];
+  let partStart = -1;
+  for (let i = 0; i <= body.length - delimiter.length; i++) {
+    if (i !== 0 && body[i - 1] !== LF) continue;
+    if (!startsWith(body, i, delimiter)) continue;
+    let partEnd = i;
+    if (partEnd > 0 && body[partEnd - 1] === LF) partEnd -= 1;
+    if (partEnd > 0 && body[partEnd - 1] === CR) partEnd -= 1;
+    if (partStart >= 0) children.push(body.subarray(partStart, partEnd));
+    let j = i + delimiter.length;
+    const closing = body[j] === 45 && body[j + 1] === 45;
+    if (closing) return children;
+    while (j < body.length && body[j] !== LF) j++;
+    partStart = j + 1;
+    i = j;
+  }
+  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;
+  return true;
+}
+function parseMime(raw) {
+  const bytes = typeof raw === "string" ? new Uint8Array(Buffer.from(raw, "utf8")) : raw;
+  const [headerEnd, bodyStart] = splitEntity(bytes);
+  const headers = parseHeaders(latin1(bytes.subarray(0, headerEnd)));
+  const body = bytes.subarray(bodyStart);
+  const acc = { parts: [], attachments: [], text: null, html: null };
+  const type = parseParams(header(headers, "content-type") ?? "text/plain");
+  if (type.main.startsWith("multipart/") && type.params.boundary) {
+    for (const child of splitMultipart(body, type.params.boundary)) walk(child, null, acc);
+  } else {
+    walk(body, headers.filter((h) => h.name.startsWith("content-")), acc);
+  }
+  return {
+    headers,
+    subject: header(headers, "subject"),
+    messageId: header(headers, "message-id"),
+    text: acc.text,
+    html: acc.html,
+    parts: acc.parts,
+    attachments: acc.attachments
+  };
+}
+
 // src/probe.ts
 async function probe(spec) {
   let response;
@@ -1266,7 +1558,7 @@ function constantTimeEquals(a, b) {
   for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
   return diff === 0;
 }
-function header(headers, name) {
+function header2(headers, name) {
   const wanted = name.toLowerCase();
   for (const [key, value] of Object.entries(headers)) {
     if (key.toLowerCase() !== wanted) continue;
@@ -1284,9 +1576,9 @@ async function verifyDelivery(trigger, delivery, secret, now) {
       reason: `${trigger.service}.${trigger.operation} declares no signature scheme, so a delivery cannot be trusted.`
     };
   }
-  const rawHeader = header(delivery.headers, spec.signatureHeader);
+  const rawHeader = header2(delivery.headers, spec.signatureHeader);
   const parsed = spec.parse && rawHeader ? spec.parse(rawHeader) : { signature: rawHeader };
-  const timestamp = parsed.timestamp ?? (spec.timestampHeader ? header(delivery.headers, spec.timestampHeader) : void 0);
+  const timestamp = parsed.timestamp ?? (spec.timestampHeader ? header2(delivery.headers, spec.timestampHeader) : void 0);
   return verifyHmac({
     raw: delivery.raw,
     signature: parsed.signature,
@@ -1359,15 +1651,19 @@ export {
   fakeValues,
   getConnectionHost,
   graphemes,
-  header,
+  header2 as header,
   hmac,
   httpFailure,
   idempotencyKeyFor,
   isEmptyPayload,
   isRemote,
   isUnconditionallyRetryable,
+  leaseAction,
+  leaseRenewAt,
+  leaseState,
   linkRanges,
   measure,
+  parseMime,
   payloadHash,
   postChain,
   probe,
@@ -1392,6 +1688,7 @@ export {
   shouldRetry,
   sliceByteRange,
   splitToFit,
+  subscriptionLease,
   triggerEvent,
   unchecked,
   utf8Length,