@particle-academy/fancy-connector-core 0.10.1 → 0.12.0

package/dist/index.d.cts

@@ -2282,6 +2282,50 @@ type MimeMessage = {
 };
 declare function parseMime(raw: Uint8Array | string): MimeMessage;
 
+/**
+ * A form-encoded body whose one named field holds JSON, decoded: the payload
+ * TRANSFORM Slack's interactivity callbacks need (`payload=<json>`).
+ *
+ * ONE implementation in two runtimes (`php/src/FormFieldJson.php` is the
+ * twin), held to the authored corpus under `fixtures/form-field-json/`. It
+ * runs AFTER signature verification, over the same raw bytes: the provider
+ * signed the form body as sent, so nothing here may be re-encoded before
+ * verifying.
+ *
+ * The decisions, each pinned by a case:
+ *
+ * - `+` and `%20` are both a space; `%XX` decodes to a byte, and the result
+ *   must be valid UTF-8.
+ * - The WHOLE body is decoded strictly. A `%` not followed by two hex digits,
+ *   anywhere, is `bad-encoding`. `decodeURIComponent` throws on `%zz` while
+ *   PHP's `urldecode` keeps it, so neither built-in is used.
+ * - The field absent is `missing-field`; present twice is `duplicate-field`,
+ *   because first-wins and last-wins are both conventions and two runtimes
+ *   choosing differently would route one click two ways.
+ * - A value that is not JSON is `not-json`, never the raw string.
+ */
+declare const FORM_FIELD_JSON_REASONS: readonly ["missing-field", "duplicate-field", "bad-encoding", "not-json"];
+type FormFieldJsonReason = (typeof FORM_FIELD_JSON_REASONS)[number];
+/** Refused BY NAME; `reason` is the same string PHP's exception carries. */
+declare class FormFieldJsonError extends Error {
+    readonly reason: FormFieldJsonReason;
+    readonly field: string;
+    constructor(reason: FormFieldJsonReason, field: string, message: string);
+}
+declare function decodeFormFieldJson(raw: Uint8Array | string, field: string): unknown;
+/**
+ * How a verified delivery is read, when its body is not plain JSON. Declared
+ * on the trigger (`TriggerDescriptor.decode`); a host verifies the raw bytes,
+ * then calls `decodeDelivery` with the declaration, then starts the run.
+ * Shipped as data too, for a host mirroring the union across a JSON boundary.
+ */
+declare const DELIVERY_DECODE_KINDS: readonly ["form-field-json"];
+type DeliveryDecode = {
+    kind: (typeof DELIVERY_DECODE_KINDS)[number];
+    field: string;
+};
+declare function decodeDelivery(decode: DeliveryDecode, raw: Uint8Array | string): unknown;
+
 /**
  * Dry-verify — proving the transport with a credential that cannot work.
  *
@@ -2424,7 +2468,7 @@ type HmacScheme = {
      * `v0:${timestamp}:${body}`, GitHub signs the body alone, and Svix signs
      * `${id}.${timestamp}.${body}` where `id` is the delivery's own id header.
      */
-    payload: (raw: string, timestamp?: string, id?: string) => string;
+    payload: (raw: string, timestamp?: string, id?: string, request?: SignedRequestLine) => string;
     /** Seconds a delivery stays acceptable. */
     tolerance?: number;
     /** Encoding of the signature the provider sends. */
@@ -2439,7 +2483,37 @@ type HmacScheme = {
     secretEncoding?: "utf8" | "base64";
     /** A prefix to strip before decoding (`whsec_`). Its absence is a refusal, never a guess. */
     secretPrefix?: string;
+    /**
+     * The unit the timestamp header is in. Seconds unless said otherwise:
+     * HubSpot sends MILLISECONDS, and comparing those with a window in seconds
+     * refuses every delivery ever made.
+     */
+    timestampUnit?: "s" | "ms";
+    /**
+     * The provider signs the REQUEST LINE too (HubSpot v3:
+     * method + uri + body + timestamp). A delivery the host passed without its
+     * method or URL is refused by name, never signed with a gap.
+     */
+    signsRequestLine?: boolean;
+    /** How the signed URI is spelled from the URL the request was sent to. */
+    uri?: SignedUriRule;
+};
+/** The URI rules a provider's signature can follow. Closed: each is a decision. */
+declare const SIGNED_URI_RULES: readonly ["hubspot-v3"];
+type SignedUriRule = (typeof SIGNED_URI_RULES)[number];
+/** The request line as signed: the method, and the URI after the scheme's rule. */
+type SignedRequestLine = {
+    method: string;
+    uri: string;
 };
+/**
+ * The URI a provider signs, from the URL the request arrived on.
+ *
+ * `hubspot-v3`: only the QUERY portion is percent-decoded, and only for twelve
+ * escapes (case-insensitive); never its leading `?`; any `#fragment` dropped.
+ * Everything else, `%26` and `%3D` included, stays as sent.
+ */
+declare function normaliseSignedUri(url: string, rule: SignedUriRule): string;
 /** The HMAC key a scheme's secret spells, or the reason it cannot be one. */
 declare function secretKeyBytes(secret: string, options?: {
     secretEncoding?: "utf8" | "base64";
@@ -2472,6 +2546,11 @@ declare function verifyHmac(options: {
     timestamp?: string;
     /** The delivery's id, when the scheme signs one (Svix's `svix-id`). */
     id?: string;
+    /** The request line as RECEIVED, when the scheme signs it (HubSpot v3). */
+    request?: {
+        method: string;
+        url: string;
+    };
     /** Seconds since the epoch. Injected so tests are not clock-dependent. */
     now?: number;
 }): Promise<WebhookVerification>;
@@ -2583,6 +2662,11 @@ declare function header(headers: Record<string, string | string[] | undefined>,
  *   SSE, CometD).
  */
 type DeliveryMechanism = "webhook" | "subscription" | "poll" | "pubsub" | "stream";
+/** See `TriggerDescriptor.route`. `path` is dotted; `[]` means every element. */
+type DeliveryRoute = {
+    by: string;
+    path: string;
+};
 type TriggerDescriptor = {
     service: string;
     operation: string;
@@ -2604,6 +2688,22 @@ type TriggerDescriptor = {
     lease?: LeaseDeclaration;
     /** For `webhook` / `subscription`: how a delivery is authenticated. */
     verification?: WebhookVerificationSpec;
+    /**
+     * For `webhook`: how the VERIFIED body is read when it is not plain JSON —
+     * Slack's interactivity is `payload=<json>`. Absent means the host reads the
+     * body as it always has. Present means the host calls `decodeDelivery` with
+     * it, over the same raw bytes the signature was checked against.
+     */
+    decode?: DeliveryDecode;
+    /**
+     * For a delivery that reaches ONE endpoint on behalf of many tenants
+     * (HubSpot app webhooks, Gmail's Pub/Sub topic): the ONLY key a host may
+     * route by, and where it sits in the verified payload. The rule that goes
+     * with it is fixed, not configurable: route only AFTER verification, only
+     * to a connection or watch the host minted, and drop an unmapped key with a
+     * 2xx and a log line, creating nothing. The package declares; the HOST routes.
+     */
+    route?: DeliveryRoute;
     /** For `poll`: the provider's smallest sane interval, in seconds. */
     minPollSeconds?: number;
     /** A faked sample event, so the node is runnable before any of the above. */
@@ -2652,6 +2752,13 @@ type InboundDelivery = {
     /** The body EXACTLY as received. Not re-serialised. See `webhook.ts`. */
     raw: string;
     headers: Record<string, string | string[] | undefined>;
+    /**
+     * The request line as RECEIVED, for a provider that signs it (HubSpot v3).
+     * Pass the full URL the provider called, scheme, host, path and query,
+     * exactly as it arrived.
+     */
+    method?: string;
+    url?: string;
 };
 /**
  * Verify an inbound delivery against a trigger's declared scheme.
@@ -2677,4 +2784,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 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, 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 Invite, type InviteMethod, type JoinTarget, type JoinTargetKind, 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 RecurrenceRule, 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, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, 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, verifySharedToken, withResolvedLimit };
+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, type JoinTarget, type JoinTargetKind, 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 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 VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, decodeDelivery, decodeFormFieldJson, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, 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, verifySharedToken, withResolvedLimit };

package/dist/index.d.ts

@@ -2282,6 +2282,50 @@ type MimeMessage = {
 };
 declare function parseMime(raw: Uint8Array | string): MimeMessage;
 
+/**
+ * A form-encoded body whose one named field holds JSON, decoded: the payload
+ * TRANSFORM Slack's interactivity callbacks need (`payload=<json>`).
+ *
+ * ONE implementation in two runtimes (`php/src/FormFieldJson.php` is the
+ * twin), held to the authored corpus under `fixtures/form-field-json/`. It
+ * runs AFTER signature verification, over the same raw bytes: the provider
+ * signed the form body as sent, so nothing here may be re-encoded before
+ * verifying.
+ *
+ * The decisions, each pinned by a case:
+ *
+ * - `+` and `%20` are both a space; `%XX` decodes to a byte, and the result
+ *   must be valid UTF-8.
+ * - The WHOLE body is decoded strictly. A `%` not followed by two hex digits,
+ *   anywhere, is `bad-encoding`. `decodeURIComponent` throws on `%zz` while
+ *   PHP's `urldecode` keeps it, so neither built-in is used.
+ * - The field absent is `missing-field`; present twice is `duplicate-field`,
+ *   because first-wins and last-wins are both conventions and two runtimes
+ *   choosing differently would route one click two ways.
+ * - A value that is not JSON is `not-json`, never the raw string.
+ */
+declare const FORM_FIELD_JSON_REASONS: readonly ["missing-field", "duplicate-field", "bad-encoding", "not-json"];
+type FormFieldJsonReason = (typeof FORM_FIELD_JSON_REASONS)[number];
+/** Refused BY NAME; `reason` is the same string PHP's exception carries. */
+declare class FormFieldJsonError extends Error {
+    readonly reason: FormFieldJsonReason;
+    readonly field: string;
+    constructor(reason: FormFieldJsonReason, field: string, message: string);
+}
+declare function decodeFormFieldJson(raw: Uint8Array | string, field: string): unknown;
+/**
+ * How a verified delivery is read, when its body is not plain JSON. Declared
+ * on the trigger (`TriggerDescriptor.decode`); a host verifies the raw bytes,
+ * then calls `decodeDelivery` with the declaration, then starts the run.
+ * Shipped as data too, for a host mirroring the union across a JSON boundary.
+ */
+declare const DELIVERY_DECODE_KINDS: readonly ["form-field-json"];
+type DeliveryDecode = {
+    kind: (typeof DELIVERY_DECODE_KINDS)[number];
+    field: string;
+};
+declare function decodeDelivery(decode: DeliveryDecode, raw: Uint8Array | string): unknown;
+
 /**
  * Dry-verify — proving the transport with a credential that cannot work.
  *
@@ -2424,7 +2468,7 @@ type HmacScheme = {
      * `v0:${timestamp}:${body}`, GitHub signs the body alone, and Svix signs
      * `${id}.${timestamp}.${body}` where `id` is the delivery's own id header.
      */
-    payload: (raw: string, timestamp?: string, id?: string) => string;
+    payload: (raw: string, timestamp?: string, id?: string, request?: SignedRequestLine) => string;
     /** Seconds a delivery stays acceptable. */
     tolerance?: number;
     /** Encoding of the signature the provider sends. */
@@ -2439,7 +2483,37 @@ type HmacScheme = {
     secretEncoding?: "utf8" | "base64";
     /** A prefix to strip before decoding (`whsec_`). Its absence is a refusal, never a guess. */
     secretPrefix?: string;
+    /**
+     * The unit the timestamp header is in. Seconds unless said otherwise:
+     * HubSpot sends MILLISECONDS, and comparing those with a window in seconds
+     * refuses every delivery ever made.
+     */
+    timestampUnit?: "s" | "ms";
+    /**
+     * The provider signs the REQUEST LINE too (HubSpot v3:
+     * method + uri + body + timestamp). A delivery the host passed without its
+     * method or URL is refused by name, never signed with a gap.
+     */
+    signsRequestLine?: boolean;
+    /** How the signed URI is spelled from the URL the request was sent to. */
+    uri?: SignedUriRule;
+};
+/** The URI rules a provider's signature can follow. Closed: each is a decision. */
+declare const SIGNED_URI_RULES: readonly ["hubspot-v3"];
+type SignedUriRule = (typeof SIGNED_URI_RULES)[number];
+/** The request line as signed: the method, and the URI after the scheme's rule. */
+type SignedRequestLine = {
+    method: string;
+    uri: string;
 };
+/**
+ * The URI a provider signs, from the URL the request arrived on.
+ *
+ * `hubspot-v3`: only the QUERY portion is percent-decoded, and only for twelve
+ * escapes (case-insensitive); never its leading `?`; any `#fragment` dropped.
+ * Everything else, `%26` and `%3D` included, stays as sent.
+ */
+declare function normaliseSignedUri(url: string, rule: SignedUriRule): string;
 /** The HMAC key a scheme's secret spells, or the reason it cannot be one. */
 declare function secretKeyBytes(secret: string, options?: {
     secretEncoding?: "utf8" | "base64";
@@ -2472,6 +2546,11 @@ declare function verifyHmac(options: {
     timestamp?: string;
     /** The delivery's id, when the scheme signs one (Svix's `svix-id`). */
     id?: string;
+    /** The request line as RECEIVED, when the scheme signs it (HubSpot v3). */
+    request?: {
+        method: string;
+        url: string;
+    };
     /** Seconds since the epoch. Injected so tests are not clock-dependent. */
     now?: number;
 }): Promise<WebhookVerification>;
@@ -2583,6 +2662,11 @@ declare function header(headers: Record<string, string | string[] | undefined>,
  *   SSE, CometD).
  */
 type DeliveryMechanism = "webhook" | "subscription" | "poll" | "pubsub" | "stream";
+/** See `TriggerDescriptor.route`. `path` is dotted; `[]` means every element. */
+type DeliveryRoute = {
+    by: string;
+    path: string;
+};
 type TriggerDescriptor = {
     service: string;
     operation: string;
@@ -2604,6 +2688,22 @@ type TriggerDescriptor = {
     lease?: LeaseDeclaration;
     /** For `webhook` / `subscription`: how a delivery is authenticated. */
     verification?: WebhookVerificationSpec;
+    /**
+     * For `webhook`: how the VERIFIED body is read when it is not plain JSON —
+     * Slack's interactivity is `payload=<json>`. Absent means the host reads the
+     * body as it always has. Present means the host calls `decodeDelivery` with
+     * it, over the same raw bytes the signature was checked against.
+     */
+    decode?: DeliveryDecode;
+    /**
+     * For a delivery that reaches ONE endpoint on behalf of many tenants
+     * (HubSpot app webhooks, Gmail's Pub/Sub topic): the ONLY key a host may
+     * route by, and where it sits in the verified payload. The rule that goes
+     * with it is fixed, not configurable: route only AFTER verification, only
+     * to a connection or watch the host minted, and drop an unmapped key with a
+     * 2xx and a log line, creating nothing. The package declares; the HOST routes.
+     */
+    route?: DeliveryRoute;
     /** For `poll`: the provider's smallest sane interval, in seconds. */
     minPollSeconds?: number;
     /** A faked sample event, so the node is runnable before any of the above. */
@@ -2652,6 +2752,13 @@ type InboundDelivery = {
     /** The body EXACTLY as received. Not re-serialised. See `webhook.ts`. */
     raw: string;
     headers: Record<string, string | string[] | undefined>;
+    /**
+     * The request line as RECEIVED, for a provider that signs it (HubSpot v3).
+     * Pass the full URL the provider called, scheme, host, path and query,
+     * exactly as it arrived.
+     */
+    method?: string;
+    url?: string;
 };
 /**
  * Verify an inbound delivery against a trigger's declared scheme.
@@ -2677,4 +2784,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 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, 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 Invite, type InviteMethod, type JoinTarget, type JoinTargetKind, 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 RecurrenceRule, 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, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, 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, verifySharedToken, withResolvedLimit };
+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, type JoinTarget, type JoinTargetKind, 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 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 VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, decodeDelivery, decodeFormFieldJson, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, 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, verifySharedToken, withResolvedLimit };

package/dist/index.js

@@ -1666,6 +1666,77 @@ function parseMime(raw) {
   };
 }
 
+// src/form-field-json.ts
+var FORM_FIELD_JSON_REASONS = ["missing-field", "duplicate-field", "bad-encoding", "not-json"];
+var FormFieldJsonError = class extends Error {
+  constructor(reason, field, message) {
+    super(message);
+    this.reason = reason;
+    this.field = field;
+    this.name = "FormFieldJsonError";
+  }
+  reason;
+  field;
+};
+var UTF8 = new TextDecoder("utf-8", { fatal: true });
+var HEX = /^[0-9A-Fa-f]{2}$/;
+function decodeFormFieldJson(raw, field) {
+  const text = typeof raw === "string" ? raw : latin12(raw);
+  const found = [];
+  for (const pair of text.split("&")) {
+    if (pair === "") continue;
+    const eq = pair.indexOf("=");
+    const name = component(eq === -1 ? pair : pair.slice(0, eq), field);
+    const value2 = component(eq === -1 ? "" : pair.slice(eq + 1), field);
+    if (name === field) found.push(value2);
+  }
+  if (found.length === 0) {
+    throw new FormFieldJsonError("missing-field", field, `the body has no "${field}" field`);
+  }
+  if (found.length > 1) {
+    throw new FormFieldJsonError("duplicate-field", field, `the body has "${field}" ${found.length} times`);
+  }
+  const [value] = found;
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new FormFieldJsonError("not-json", field, `"${field}" is not JSON: ${error.message}`);
+  }
+}
+function component(encoded, field) {
+  const bytes = [];
+  for (let i = 0; i < encoded.length; i++) {
+    const char = encoded[i];
+    if (char === "+") {
+      bytes.push(32);
+    } else if (char === "%") {
+      const hex = encoded.slice(i + 1, i + 3);
+      if (!HEX.test(hex)) {
+        throw new FormFieldJsonError("bad-encoding", field, `a "%" at byte ${i} is not followed by two hex digits`);
+      }
+      bytes.push(parseInt(hex, 16));
+      i += 2;
+    } else {
+      bytes.push(encoded.charCodeAt(i) & 255);
+    }
+  }
+  try {
+    return UTF8.decode(new Uint8Array(bytes));
+  } catch {
+    throw new FormFieldJsonError("bad-encoding", field, "the decoded bytes are not valid UTF-8");
+  }
+}
+var DELIVERY_DECODE_KINDS = ["form-field-json"];
+function decodeDelivery(decode, raw) {
+  if (decode.kind === "form-field-json") return decodeFormFieldJson(raw, decode.field);
+  throw new Error(`unknown decode kind ${JSON.stringify(decode.kind)}`);
+}
+function latin12(bytes) {
+  let out = "";
+  for (const byte of bytes) out += String.fromCharCode(byte);
+  return out;
+}
+
 // src/probe.ts
 async function probe(spec) {
   let response;
@@ -1882,6 +1953,29 @@ var PROBLEM_SEVERITIES = ["block", "warn"];
 var CANONICAL_METRICS = ["like", "share", "reply", "quote", "view"];
 
 // src/webhook.ts
+var SIGNED_URI_RULES = ["hubspot-v3"];
+var HUBSPOT_V3_DECODE = {
+  "%3A": ":",
+  "%2F": "/",
+  "%3F": "?",
+  "%40": "@",
+  "%21": "!",
+  "%24": "$",
+  "%27": "'",
+  "%28": "(",
+  "%29": ")",
+  "%2A": "*",
+  "%2C": ",",
+  "%3B": ";"
+};
+function normaliseSignedUri(url, rule) {
+  if (rule !== "hubspot-v3") throw new Error(`unknown signed-uri rule ${JSON.stringify(rule)}`);
+  const withoutFragment = url.split("#", 1)[0] ?? "";
+  const q = withoutFragment.indexOf("?");
+  if (q === -1) return withoutFragment;
+  const query = withoutFragment.slice(q + 1).replace(/%[0-9A-Fa-f]{2}/g, (e) => HUBSPOT_V3_DECODE[e.toUpperCase()] ?? e);
+  return `${withoutFragment.slice(0, q)}?${query}`;
+}
 function secretKeyBytes(secret, options = {}) {
   let material = secret;
   if (options.secretPrefix !== void 0) {
@@ -1916,13 +2010,26 @@ async function verifyHmac(options) {
     const sent = Number(timestamp);
     if (!Number.isFinite(sent)) return { ok: false, reason: "timestamp header is not a number" };
     const now = options.now ?? Math.floor(Date.now() / 1e3);
-    if (Math.abs(now - sent) > scheme.tolerance) {
+    const sentSeconds = scheme.timestampUnit === "ms" ? sent / 1e3 : sent;
+    if (Math.abs(now - sentSeconds) > scheme.tolerance) {
       return { ok: false, reason: `delivery is outside the ${scheme.tolerance}s replay window` };
     }
   }
   const key = secretKeyBytes(secret, scheme);
   if ("reason" in key) return { ok: false, reason: key.reason };
-  const expected = await hmac(secret, scheme.payload(raw, timestamp, id), scheme.algorithm, scheme.encoding ?? "hex", scheme);
+  let line;
+  if (scheme.signsRequestLine) {
+    const { method, url } = options.request ?? {};
+    if (!method || !url) return { ok: false, reason: "delivery carried no request method or url" };
+    line = { method, uri: scheme.uri ? normaliseSignedUri(url, scheme.uri) : url };
+  }
+  const expected = await hmac(
+    secret,
+    scheme.payload(raw, timestamp, id, line),
+    scheme.algorithm,
+    scheme.encoding ?? "hex",
+    scheme
+  );
   return signatures.some((candidate) => constantTimeEquals(expected, candidate)) ? { ok: true } : { ok: false, reason: "signature did not match" };
 }
 async function hmac(secret, payload, algorithm, encoding = "hex", options = {}) {
@@ -2047,6 +2154,7 @@ async function verifyDelivery(trigger, delivery, secret, now) {
     scheme: spec.scheme,
     timestamp,
     id,
+    ...delivery.method === void 0 && delivery.url === void 0 ? {} : { request: { method: delivery.method ?? "", url: delivery.url ?? "" } },
     ...now === void 0 ? {} : { now }
   });
 }
@@ -2087,14 +2195,18 @@ export {
   ConnectorUnreachable,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY,
+  DELIVERY_DECODE_KINDS,
   EXPIRES_AT_UNITS,
   FAKE_EPOCH,
+  FORM_FIELD_JSON_REASONS,
+  FormFieldJsonError,
   MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING,
   PROBLEM_SEVERITIES,
   RENDERER_VERSION,
   REVIEW_STALE_DAYS,
   SANDBOX_KINDS,
+  SIGNED_URI_RULES,
   SUPPORTED_CONNECTOR_API,
   assertConnectorApi,
   byteRangeOf,
@@ -2109,6 +2221,8 @@ export {
   compareShape,
   connectionsFor,
   constantTimeEquals,
+  decodeDelivery,
+  decodeFormFieldJson,
   deliver,
   fakeRequest,
   fakeValues,
@@ -2132,6 +2246,7 @@ export {
   linkRanges,
   measure,
   nextOccurrence,
+  normaliseSignedUri,
   parseInvite,
   parseMime,
   payloadHash,