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

package/dist/index.d.cts

@@ -2048,11 +2048,27 @@ type CredentialField = {
     /** A hint for an empty field. NEVER a real value. */
     placeholder?: string;
 };
+/** Who performs a setup step. Ships as data: a host mirrors it across JSON. */
+declare const SETUP_ACTORS: readonly ["person", "agent"];
+type SetupActor = (typeof SETUP_ACTORS)[number];
 type SetupStep = {
     title: string;
     /** The step, and the trap in it. A step with no trap named is usually wrong. */
     detail: string;
     url?: string;
+    /** Who does it. Absent means `person` (0.15.0). */
+    actor?: SetupActor;
+    /** What an agent is asked to do. Required when `actor` is `agent`. */
+    prompt?: string;
+    /** Values the person pastes somewhere, e.g. the callback URL. */
+    copy?: {
+        label: string;
+        value: string;
+    }[];
+    /** The credential keys this step yields. */
+    fields?: string[];
+    /** How the person knows the step is done. */
+    done?: string;
 };
 /**
  * The result of a read-only credential check.
@@ -2850,6 +2866,40 @@ type PubSubPushMessage = {
 };
 declare function decodePubSubPush(raw: Uint8Array | string): PubSubPushMessage;
 
+/**
+ * A connector's setup steps, rendered for ONE app.
+ *
+ * A definition is written once for every host, so the values that differ per
+ * host — where its webhooks live, what it calls itself, which connector this
+ * is — are tokens: `{{appUrl}}`, `{{appName}}`, `{{connector}}`, and only
+ * those. Held to `fixtures/setup-render/cases.json`, mirrored in
+ * `php/src/Setup.php`.
+ *
+ * Two refusals, both BY NAME, because each would otherwise reach a person as a
+ * broken instruction that looks deliberate:
+ *
+ * - `unknown-token`: anything else shaped like `{{...}}` — a typo, a spaced
+ *   `{{ appUrl }}`, a token a definition invented. Left in, a person pastes a
+ *   literal brace into a provider console.
+ * - `missing-context`: a token the host gave no (or an empty) value for. Left
+ *   empty, a callback URL becomes `/hooks/twilio` and points nowhere.
+ *
+ * `appUrl` loses ONE trailing slash first, so `{{appUrl}}/hooks` never doubles
+ * it. A context value is inserted once and never expanded again.
+ */
+
+declare const SETUP_TOKENS: readonly ["appUrl", "appName", "connector"];
+type SetupToken = (typeof SETUP_TOKENS)[number];
+declare const SETUP_RENDER_REASONS: readonly ["unknown-token", "missing-context"];
+type SetupRenderReason = (typeof SETUP_RENDER_REASONS)[number];
+type SetupContext = Partial<Record<SetupToken, string>>;
+declare class SetupRenderError extends Error {
+    readonly reason: SetupRenderReason;
+    constructor(reason: SetupRenderReason, message: string);
+}
+/** Render every step for one app: tokens filled, `actor` and `fields` defaulted. */
+declare function renderSetup(steps: readonly SetupStep[], context: SetupContext): SetupStep[];
+
 /**
  * How a connector trigger learns that something happened.
  *
@@ -3012,4 +3062,4 @@ oidc?: OidcExpectation): Promise<WebhookVerification>;
  */
 declare function triggerEvent(trigger: TriggerDescriptor, connection: ResolvedConnection, injected: unknown, config: Record<string, unknown>): unknown;
 
-export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type Attendee, type ByteRange, CANONICAL_METRICS, CONNECTOR_API_VERSION, CONNECTOR_MODES, CREDENTIAL_SCOPES, CURSOR_READ_REASONS, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type ChallengeHandshake, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, type CredentialScope, CursorReadError, type CursorReadReason, type CursorReadResult, type CursorReadSpec, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, DELIVERY_DECODE_KINDS, type DeliveryDeclaration, type DeliveryDecode, type DeliveryMechanism, type DeliveryOutcome, type DeliveryRoute, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, FORM_FIELD_JSON_REASONS, type FailureKind, type FakeRequest, type FakeValues, FormFieldJsonError, type FormFieldJsonReason, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type Invite, type InviteMethod, JWT_ALGORITHMS, type JoinTarget, type JoinTargetKind, type Jwk, type JwtVerification, type LeaseAction, type LeaseDeclaration, type LeaseState, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type MimeAttachment, type MimeHeader, type MimeMessage, type MimePart, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, OIDC_JWT_SCHEME_KIND, type OidcExpectation, type OidcJwtScheme, type OidcJwtVerificationSpec, PROBLEM_SEVERITIES, PUBSUB_PUSH_REASONS, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, PubSubPushError, type PubSubPushMessage, type PubSubPushReason, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RecurrenceRule, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SIGNED_URI_RULES, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SignedRequestLine, type SignedUriRule, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyJwtOptions, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, decodeDelivery, decodeFormFieldJson, decodePubSubPush, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isOidcJwtScheme, isOidcJwtSpec, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, normaliseSignedUri, parseInvite, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, readWithCursor, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, secretKeyBytes, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifyJwt, verifyOidcDelivery, verifySharedToken, withResolvedLimit };
+export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type Attendee, type ByteRange, CANONICAL_METRICS, CONNECTOR_API_VERSION, CONNECTOR_MODES, CREDENTIAL_SCOPES, CURSOR_READ_REASONS, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type ChallengeHandshake, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, type CredentialScope, CursorReadError, type CursorReadReason, type CursorReadResult, type CursorReadSpec, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, DELIVERY_DECODE_KINDS, type DeliveryDeclaration, type DeliveryDecode, type DeliveryMechanism, type DeliveryOutcome, type DeliveryRoute, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, FORM_FIELD_JSON_REASONS, type FailureKind, type FakeRequest, type FakeValues, FormFieldJsonError, type FormFieldJsonReason, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type Invite, type InviteMethod, JWT_ALGORITHMS, type JoinTarget, type JoinTargetKind, type Jwk, type JwtVerification, type LeaseAction, type LeaseDeclaration, type LeaseState, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type MimeAttachment, type MimeHeader, type MimeMessage, type MimePart, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, OIDC_JWT_SCHEME_KIND, type OidcExpectation, type OidcJwtScheme, type OidcJwtVerificationSpec, PROBLEM_SEVERITIES, PUBSUB_PUSH_REASONS, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, PubSubPushError, type PubSubPushMessage, type PubSubPushReason, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RecurrenceRule, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SETUP_ACTORS, SETUP_RENDER_REASONS, SETUP_TOKENS, SIGNED_URI_RULES, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupActor, type SetupContext, SetupRenderError, type SetupRenderReason, type SetupStep, type SetupToken, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SignedRequestLine, type SignedUriRule, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyJwtOptions, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, decodeDelivery, decodeFormFieldJson, decodePubSubPush, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isOidcJwtScheme, isOidcJwtSpec, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, normaliseSignedUri, parseInvite, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, readWithCursor, registerConnectionHost, registerTransport, render, renderSetup, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, secretKeyBytes, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifyJwt, verifyOidcDelivery, verifySharedToken, withResolvedLimit };

package/dist/index.d.ts

@@ -2048,11 +2048,27 @@ type CredentialField = {
     /** A hint for an empty field. NEVER a real value. */
     placeholder?: string;
 };
+/** Who performs a setup step. Ships as data: a host mirrors it across JSON. */
+declare const SETUP_ACTORS: readonly ["person", "agent"];
+type SetupActor = (typeof SETUP_ACTORS)[number];
 type SetupStep = {
     title: string;
     /** The step, and the trap in it. A step with no trap named is usually wrong. */
     detail: string;
     url?: string;
+    /** Who does it. Absent means `person` (0.15.0). */
+    actor?: SetupActor;
+    /** What an agent is asked to do. Required when `actor` is `agent`. */
+    prompt?: string;
+    /** Values the person pastes somewhere, e.g. the callback URL. */
+    copy?: {
+        label: string;
+        value: string;
+    }[];
+    /** The credential keys this step yields. */
+    fields?: string[];
+    /** How the person knows the step is done. */
+    done?: string;
 };
 /**
  * The result of a read-only credential check.
@@ -2850,6 +2866,40 @@ type PubSubPushMessage = {
 };
 declare function decodePubSubPush(raw: Uint8Array | string): PubSubPushMessage;
 
+/**
+ * A connector's setup steps, rendered for ONE app.
+ *
+ * A definition is written once for every host, so the values that differ per
+ * host — where its webhooks live, what it calls itself, which connector this
+ * is — are tokens: `{{appUrl}}`, `{{appName}}`, `{{connector}}`, and only
+ * those. Held to `fixtures/setup-render/cases.json`, mirrored in
+ * `php/src/Setup.php`.
+ *
+ * Two refusals, both BY NAME, because each would otherwise reach a person as a
+ * broken instruction that looks deliberate:
+ *
+ * - `unknown-token`: anything else shaped like `{{...}}` — a typo, a spaced
+ *   `{{ appUrl }}`, a token a definition invented. Left in, a person pastes a
+ *   literal brace into a provider console.
+ * - `missing-context`: a token the host gave no (or an empty) value for. Left
+ *   empty, a callback URL becomes `/hooks/twilio` and points nowhere.
+ *
+ * `appUrl` loses ONE trailing slash first, so `{{appUrl}}/hooks` never doubles
+ * it. A context value is inserted once and never expanded again.
+ */
+
+declare const SETUP_TOKENS: readonly ["appUrl", "appName", "connector"];
+type SetupToken = (typeof SETUP_TOKENS)[number];
+declare const SETUP_RENDER_REASONS: readonly ["unknown-token", "missing-context"];
+type SetupRenderReason = (typeof SETUP_RENDER_REASONS)[number];
+type SetupContext = Partial<Record<SetupToken, string>>;
+declare class SetupRenderError extends Error {
+    readonly reason: SetupRenderReason;
+    constructor(reason: SetupRenderReason, message: string);
+}
+/** Render every step for one app: tokens filled, `actor` and `fields` defaulted. */
+declare function renderSetup(steps: readonly SetupStep[], context: SetupContext): SetupStep[];
+
 /**
  * How a connector trigger learns that something happened.
  *
@@ -3012,4 +3062,4 @@ oidc?: OidcExpectation): Promise<WebhookVerification>;
  */
 declare function triggerEvent(trigger: TriggerDescriptor, connection: ResolvedConnection, injected: unknown, config: Record<string, unknown>): unknown;
 
-export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type Attendee, type ByteRange, CANONICAL_METRICS, CONNECTOR_API_VERSION, CONNECTOR_MODES, CREDENTIAL_SCOPES, CURSOR_READ_REASONS, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type ChallengeHandshake, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, type CredentialScope, CursorReadError, type CursorReadReason, type CursorReadResult, type CursorReadSpec, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, DELIVERY_DECODE_KINDS, type DeliveryDeclaration, type DeliveryDecode, type DeliveryMechanism, type DeliveryOutcome, type DeliveryRoute, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, FORM_FIELD_JSON_REASONS, type FailureKind, type FakeRequest, type FakeValues, FormFieldJsonError, type FormFieldJsonReason, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type Invite, type InviteMethod, JWT_ALGORITHMS, type JoinTarget, type JoinTargetKind, type Jwk, type JwtVerification, type LeaseAction, type LeaseDeclaration, type LeaseState, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type MimeAttachment, type MimeHeader, type MimeMessage, type MimePart, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, OIDC_JWT_SCHEME_KIND, type OidcExpectation, type OidcJwtScheme, type OidcJwtVerificationSpec, PROBLEM_SEVERITIES, PUBSUB_PUSH_REASONS, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, PubSubPushError, type PubSubPushMessage, type PubSubPushReason, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RecurrenceRule, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SIGNED_URI_RULES, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SignedRequestLine, type SignedUriRule, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyJwtOptions, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, decodeDelivery, decodeFormFieldJson, decodePubSubPush, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isOidcJwtScheme, isOidcJwtSpec, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, normaliseSignedUri, parseInvite, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, readWithCursor, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, secretKeyBytes, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifyJwt, verifyOidcDelivery, verifySharedToken, withResolvedLimit };
+export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type Attendee, type ByteRange, CANONICAL_METRICS, CONNECTOR_API_VERSION, CONNECTOR_MODES, CREDENTIAL_SCOPES, CURSOR_READ_REASONS, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type ChallengeHandshake, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, type CredentialScope, CursorReadError, type CursorReadReason, type CursorReadResult, type CursorReadSpec, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, DELIVERY_DECODE_KINDS, type DeliveryDeclaration, type DeliveryDecode, type DeliveryMechanism, type DeliveryOutcome, type DeliveryRoute, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, FORM_FIELD_JSON_REASONS, type FailureKind, type FakeRequest, type FakeValues, FormFieldJsonError, type FormFieldJsonReason, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type Invite, type InviteMethod, JWT_ALGORITHMS, type JoinTarget, type JoinTargetKind, type Jwk, type JwtVerification, type LeaseAction, type LeaseDeclaration, type LeaseState, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type MimeAttachment, type MimeHeader, type MimeMessage, type MimePart, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, OIDC_JWT_SCHEME_KIND, type OidcExpectation, type OidcJwtScheme, type OidcJwtVerificationSpec, PROBLEM_SEVERITIES, PUBSUB_PUSH_REASONS, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, PubSubPushError, type PubSubPushMessage, type PubSubPushReason, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RecurrenceRule, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SETUP_ACTORS, SETUP_RENDER_REASONS, SETUP_TOKENS, SIGNED_URI_RULES, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupActor, type SetupContext, SetupRenderError, type SetupRenderReason, type SetupStep, type SetupToken, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SignedRequestLine, type SignedUriRule, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyJwtOptions, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, decodeDelivery, decodeFormFieldJson, decodePubSubPush, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isOidcJwtScheme, isOidcJwtSpec, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, normaliseSignedUri, parseInvite, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, readWithCursor, registerConnectionHost, registerTransport, render, renderSetup, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, secretKeyBytes, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifyJwt, verifyOidcDelivery, verifySharedToken, withResolvedLimit };

package/dist/index.js

@@ -2354,6 +2354,53 @@ function withResolvedLimit(rules, limit) {
 var CREDENTIAL_SCOPES = ["provider", "account"];
 var PROBLEM_SEVERITIES = ["block", "warn"];
 var CANONICAL_METRICS = ["like", "share", "reply", "quote", "view"];
+var SETUP_ACTORS = ["person", "agent"];
+
+// src/setup.ts
+var SETUP_TOKENS = ["appUrl", "appName", "connector"];
+var SETUP_RENDER_REASONS = ["unknown-token", "missing-context"];
+var SetupRenderError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "SetupRenderError";
+  }
+  reason;
+};
+var TOKEN = /\{\{([^{}]*)\}\}/g;
+function fill(text, context) {
+  return text.replace(TOKEN, (whole, name) => {
+    if (!SETUP_TOKENS.includes(name)) {
+      throw new SetupRenderError(
+        "unknown-token",
+        `setup step text uses ${whole}, which is not one of ${SETUP_TOKENS.map((t) => `{{${t}}}`).join(", ")}`
+      );
+    }
+    let value = context[name];
+    if (value === void 0 || value === null || value === "") {
+      throw new SetupRenderError("missing-context", `setup step text uses ${whole} and the host gave no value for ${name}`);
+    }
+    if (name === "appUrl" && value.endsWith("/")) value = value.slice(0, -1);
+    return value;
+  });
+}
+function renderSetup(steps, context) {
+  return steps.map((step) => {
+    const out = {
+      title: fill(step.title, context),
+      detail: fill(step.detail, context),
+      actor: step.actor ?? "person",
+      fields: [...step.fields ?? []]
+    };
+    if (step.url !== void 0) out.url = fill(step.url, context);
+    if (step.prompt !== void 0) out.prompt = fill(step.prompt, context);
+    if (step.done !== void 0) out.done = fill(step.done, context);
+    if (step.copy !== void 0) {
+      out.copy = step.copy.map((c) => ({ label: fill(c.label, context), value: fill(c.value, context) }));
+    }
+    return out;
+  });
+}
 
 // src/trigger.ts
 function isOidcJwtSpec(spec) {
@@ -2458,8 +2505,12 @@ export {
   RENDERER_VERSION,
   REVIEW_STALE_DAYS,
   SANDBOX_KINDS,
+  SETUP_ACTORS,
+  SETUP_RENDER_REASONS,
+  SETUP_TOKENS,
   SIGNED_URI_RULES,
   SUPPORTED_CONNECTOR_API,
+  SetupRenderError,
   assertConnectorApi,
   byteRangeOf,
   callConnector,
@@ -2513,6 +2564,7 @@ export {
   registerConnectionHost,
   registerTransport,
   render,
+  renderSetup,
   reported,
   resetRateState,
   resolveConnection,