@particle-academy/fancy-connector-core 0.0.0 → 0.2.0

package/dist/index.d.cts

@@ -37,8 +37,22 @@
  * one status id, Telegram needs a message id and a chat. A shape naming one
  * provider's model would be wrong for the next one, so the chain carries
  * whatever the poster returned and never reads inside it.
- */
-type ChainRef = Record<string, string | number>;
+ *
+ * **`object`, not `Record<string, string | number>`** — and the difference is
+ * not pedantry. An ordinary interface does not satisfy an index signature
+ * unless it declares one, so `interface PostRef { uri: string; cid: string }`
+ * did NOT satisfy the old constraint. The reference consumer worked around it
+ * with `postChain<T & ChainRef>` plus two `as unknown as` casts, and could not
+ * use `ChainOutcome<T>` in their own signatures at all — because the only other
+ * fix was to add an index signature to a type used across their codebase in
+ * order to satisfy a generic used in one place, which weakens the type
+ * everywhere to please one call site.
+ *
+ * A constraint everyone casts past is not enforcing anything; it is just making
+ * the casts. `object` still rejects the mistake worth rejecting — a primitive
+ * as a reference — and accepts every real one.
+ */
+type ChainRef = object;
 type ChainLinks<Ref extends ChainRef> = {
     /** The top of the conversation. Fixed for the whole chain. */
     root: Ref;
@@ -496,10 +510,39 @@ declare const CONNECTOR_MODES: ConnectorMode[];
  * - `base-url` — a different host entirely (PayPal's `api-m.sandbox.paypal.com`).
  * - `separate-account` — a distinct tenant you must create, often with its own
  *   login host (Salesforce sandbox orgs on `test.salesforce.com`).
+ * - `restricted-reach` — there is no separate estate at all; what the provider
+ *   offers instead is an **account-level restriction on who can see the
+ *   result**. A Meta app in Development Mode; an unaudited TikTok app that can
+ *   only post `SELF_ONLY`. Same credentials, same endpoints, same estate — only
+ *   the audience changes, and nothing in a request selects it.
+ *
+ *   **This is the dangerous one**, and it is why it is not folded into `none`.
+ *   It is the shape most likely to be mistaken for a sandbox, because it looks
+ *   exactly like a successful post that nobody can see: `ok: true`, a real id,
+ *   no audience. `none` says "there is nothing"; this says "there is something,
+ *   it is not selectable from here, and success does not mean reach".
  * - `none` — the provider has no test estate. `sandbox` is then not offered at
- *   all, and the node's honest choices are `fake` and `live`.
- */
-type SandboxKind = "credential" | "base-url" | "separate-account" | "none";
+ *   all, and the honest choices are `fake` and `live`.
+ * - `unverified` — **nobody has checked yet.** A real state, and the type has to
+ *   carry it: this is the field where being wrong sends someone to a live
+ *   estate believing it is a test one, so "researched but not verified" must not
+ *   be forced to pick one of the other five. It belongs on a provider declared
+ *   `implemented: false`; on one declared `implemented: true` it is a finding,
+ *   and `providerProblems()` reports it.
+ */
+type SandboxKind = "credential" | "base-url" | "separate-account" | "restricted-reach" | "none" | "unverified";
+/** Every value, as data, for a host validating input that crossed a JSON boundary. */
+declare const SANDBOX_KINDS: readonly SandboxKind[];
+declare function sandboxIsSelectable(kind: SandboxKind): boolean;
+/**
+ * Why `mode: "sandbox"` cannot be honoured for this kind, in the words the
+ * person reading it needs.
+ *
+ * Three reasons, three messages. Collapsing them into "no sandbox available"
+ * would hide the one that matters: `restricted-reach` is not an absence, it is
+ * a different mechanism with a trap in it.
+ */
+declare function sandboxRefusal(service: string, kind: SandboxKind): string;
 /** The host's view of where it is running. Kept tiny so it is trivial to fake. */
 type HostEnvironment = {
     /** True only in a real production deployment. Everything else is "local". */
@@ -1461,7 +1504,29 @@ type RenderedPayload = {
  * ignores this; the point of the rule set is that most do not have to.
  */
 type RenderRules = {
-    /** The provider's limit per message, or null where it has none. */
+    /**
+     * The provider's limit per message, or `null` where it imposes none.
+     *
+     * **`null` means UNCOUNTED, and it is a real answer** — distinct from "we do
+     * not know", which is not a renderable state at all. A caller that does not
+     * know the limit must find out before rendering, because every alternative
+     * silently produces the wrong bytes.
+     *
+     * ## This must stay RESOLVABLE PER CONNECTION, and never become static
+     *
+     * A Mastodon instance's character limit comes from the server it is running:
+     * one instance allows 500, another 5000, and the same connector talks to
+     * both. Baking the limit into the connector breaks in the quietest way
+     * available — rendering to 500 on an instance that allows 5000 wastes most of
+     * a post, and rendering to 5000 on one that allows 500 produces a refusal the
+     * author cannot see coming from the preview.
+     *
+     * So the limit is resolved by the CALLER, from the connection, and passed IN
+     * — which is also what makes it part of what was approved rather than
+     * something decided later behind the approver's back. `withResolvedLimit()`
+     * is the supported way to do that, and a test pins that per-call rules beat
+     * declared ones.
+     */
     limit: number | null;
     unit: TextUnit;
     /**
@@ -1529,6 +1594,19 @@ declare function payloadHash(payload: RenderedPayload): Promise<string>;
  * every one of those checks from being hollow.
  */
 declare function isEmptyPayload(payload: RenderedPayload): boolean;
+/**
+ * Apply a per-connection limit over a connector's declared rules.
+ *
+ * The one supported way to do the thing `RenderRules.limit` insists on: a
+ * Mastodon instance publishes its own `max_toot_chars`, a Discord webhook does
+ * not, and the same connector serves both. Resolving happens at the call site,
+ * with the connection in hand, and the resolved value travels INTO `render` so
+ * it is part of the payload the approver saw.
+ *
+ * `undefined` keeps whatever the connector declared — "I did not look" is not
+ * the same as "there is no limit", and only the second is `null`.
+ */
+declare function withResolvedLimit(rules: RenderRules, limit: number | null | undefined): RenderRules;
 
 /**
  * The seam — two objects, deliberately separate.
@@ -1576,6 +1654,28 @@ declare function isEmptyPayload(payload: RenderedPayload): boolean;
  * path — and the reference implementation very nearly stored it as
  * configuration because it looked like a URL.
  */
+/**
+ * Who a credential belongs to.
+ *
+ * Exported as a runtime constant as well as a type — see `CREDENTIAL_SCOPES`.
+ */
+type CredentialScope = "provider" | "account";
+/**
+ * The scopes, as DATA.
+ *
+ * Because this union crosses a JSON boundary and the compiler cannot follow it
+ * there. When these values were renamed from `app`/`brand`, a consumer that
+ * re-declared the field shape on its client kept compiling — their
+ * `f.scope === "brand"` silently became never-true, and every credential field
+ * would have rendered as shared. `tsc` gives a host mirroring these types no
+ * help at all, so the values ship as data a host can validate against at the
+ * boundary where the compiler stops.
+ */
+declare const CREDENTIAL_SCOPES: readonly CredentialScope[];
+/** Severities, as data, for the same reason. */
+declare const PROBLEM_SEVERITIES: readonly ["block", "warn"];
+/** Canonical metric names, as data, for the same reason. */
+declare const CANONICAL_METRICS: readonly ["like", "share", "reply", "quote", "view"];
 type CredentialField = {
     /** Stable key. The host maps it to wherever it keeps values. */
     key: string;
@@ -1589,7 +1689,7 @@ type CredentialField = {
      * The distinction exists because getting it wrong means either asking for the
      * same app secret five times or letting one account's token reach another's.
      */
-    scope: "provider" | "account";
+    scope: CredentialScope;
     secret: boolean;
     required: boolean;
     /** A hint for an empty field. NEVER a real value. */
@@ -1642,8 +1742,26 @@ type ProviderAdapter = {
      * that anything can be revoked. "No known expiry" is not "cannot stop working".
      */
     credentialLifetimeDays?: number;
-    /** How the provider exposes a test estate, in the four shapes that exist. */
+    /**
+     * How the provider exposes a test estate.
+     *
+     * **`"unverified"` is a real answer and is the right one until somebody has
+     * actually checked.** Being wrong here points a workflow at a live estate
+     * while a person believes it is a test one, so the type carries "nobody
+     * looked" rather than forcing a guess — a comment saying so is not a type, and
+     * `providerProblems()` reports the combination `implemented: true` +
+     * `unverified`.
+     */
     sandbox: SandboxKind;
+    /**
+     * What `verify` proves, and what it does NOT.
+     *
+     * Required whenever `verify` exists, and checked by `providerProblems()`.
+     * Telegram's `getMe` validates the token and says nothing about whether the
+     * bot was added to the target chat — which is the step everyone actually gets
+     * stuck on. A green tick that means more than it should is worse than no tick.
+     */
+    proves?: string;
     /**
      * A read-only call proving the credential works AND reaches the right account.
      *
@@ -1860,6 +1978,22 @@ declare function capabilityProblems(connector: Connector<never>): string[];
  * `undefined` and non-numbers do not.
  */
 declare function reported(values: Record<string, unknown>): Record<string, number>;
+/**
+ * Every way a PROVIDER's declaration can outrun what anyone actually checked.
+ *
+ * The sibling of `capabilityProblems`, one level up. `capabilities.metrics: true`
+ * with no shape turns an unimplemented feature into a reported zero; the
+ * equivalent here turns *nobody looked* into a statement about a test estate —
+ * and that field is the one where being wrong sends a person to a live estate
+ * believing it is a test one.
+ *
+ * Strings rather than a throw, so a host reports all of them at once. A check
+ * that stops at the first problem trains people to fix one thing and re-run,
+ * which is how a list of six becomes six rounds.
+ */
+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;
 
 /**
  * Dry-verify — proving the transport with a credential that cannot work.
@@ -2126,4 +2260,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, CONNECTOR_API_VERSION, CONNECTOR_MODES, 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, 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, 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, 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, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, satisfiesMinimum, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac };
+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 };

package/dist/index.d.ts

@@ -37,8 +37,22 @@
  * one status id, Telegram needs a message id and a chat. A shape naming one
  * provider's model would be wrong for the next one, so the chain carries
  * whatever the poster returned and never reads inside it.
- */
-type ChainRef = Record<string, string | number>;
+ *
+ * **`object`, not `Record<string, string | number>`** — and the difference is
+ * not pedantry. An ordinary interface does not satisfy an index signature
+ * unless it declares one, so `interface PostRef { uri: string; cid: string }`
+ * did NOT satisfy the old constraint. The reference consumer worked around it
+ * with `postChain<T & ChainRef>` plus two `as unknown as` casts, and could not
+ * use `ChainOutcome<T>` in their own signatures at all — because the only other
+ * fix was to add an index signature to a type used across their codebase in
+ * order to satisfy a generic used in one place, which weakens the type
+ * everywhere to please one call site.
+ *
+ * A constraint everyone casts past is not enforcing anything; it is just making
+ * the casts. `object` still rejects the mistake worth rejecting — a primitive
+ * as a reference — and accepts every real one.
+ */
+type ChainRef = object;
 type ChainLinks<Ref extends ChainRef> = {
     /** The top of the conversation. Fixed for the whole chain. */
     root: Ref;
@@ -496,10 +510,39 @@ declare const CONNECTOR_MODES: ConnectorMode[];
  * - `base-url` — a different host entirely (PayPal's `api-m.sandbox.paypal.com`).
  * - `separate-account` — a distinct tenant you must create, often with its own
  *   login host (Salesforce sandbox orgs on `test.salesforce.com`).
+ * - `restricted-reach` — there is no separate estate at all; what the provider
+ *   offers instead is an **account-level restriction on who can see the
+ *   result**. A Meta app in Development Mode; an unaudited TikTok app that can
+ *   only post `SELF_ONLY`. Same credentials, same endpoints, same estate — only
+ *   the audience changes, and nothing in a request selects it.
+ *
+ *   **This is the dangerous one**, and it is why it is not folded into `none`.
+ *   It is the shape most likely to be mistaken for a sandbox, because it looks
+ *   exactly like a successful post that nobody can see: `ok: true`, a real id,
+ *   no audience. `none` says "there is nothing"; this says "there is something,
+ *   it is not selectable from here, and success does not mean reach".
  * - `none` — the provider has no test estate. `sandbox` is then not offered at
- *   all, and the node's honest choices are `fake` and `live`.
- */
-type SandboxKind = "credential" | "base-url" | "separate-account" | "none";
+ *   all, and the honest choices are `fake` and `live`.
+ * - `unverified` — **nobody has checked yet.** A real state, and the type has to
+ *   carry it: this is the field where being wrong sends someone to a live
+ *   estate believing it is a test one, so "researched but not verified" must not
+ *   be forced to pick one of the other five. It belongs on a provider declared
+ *   `implemented: false`; on one declared `implemented: true` it is a finding,
+ *   and `providerProblems()` reports it.
+ */
+type SandboxKind = "credential" | "base-url" | "separate-account" | "restricted-reach" | "none" | "unverified";
+/** Every value, as data, for a host validating input that crossed a JSON boundary. */
+declare const SANDBOX_KINDS: readonly SandboxKind[];
+declare function sandboxIsSelectable(kind: SandboxKind): boolean;
+/**
+ * Why `mode: "sandbox"` cannot be honoured for this kind, in the words the
+ * person reading it needs.
+ *
+ * Three reasons, three messages. Collapsing them into "no sandbox available"
+ * would hide the one that matters: `restricted-reach` is not an absence, it is
+ * a different mechanism with a trap in it.
+ */
+declare function sandboxRefusal(service: string, kind: SandboxKind): string;
 /** The host's view of where it is running. Kept tiny so it is trivial to fake. */
 type HostEnvironment = {
     /** True only in a real production deployment. Everything else is "local". */
@@ -1461,7 +1504,29 @@ type RenderedPayload = {
  * ignores this; the point of the rule set is that most do not have to.
  */
 type RenderRules = {
-    /** The provider's limit per message, or null where it has none. */
+    /**
+     * The provider's limit per message, or `null` where it imposes none.
+     *
+     * **`null` means UNCOUNTED, and it is a real answer** — distinct from "we do
+     * not know", which is not a renderable state at all. A caller that does not
+     * know the limit must find out before rendering, because every alternative
+     * silently produces the wrong bytes.
+     *
+     * ## This must stay RESOLVABLE PER CONNECTION, and never become static
+     *
+     * A Mastodon instance's character limit comes from the server it is running:
+     * one instance allows 500, another 5000, and the same connector talks to
+     * both. Baking the limit into the connector breaks in the quietest way
+     * available — rendering to 500 on an instance that allows 5000 wastes most of
+     * a post, and rendering to 5000 on one that allows 500 produces a refusal the
+     * author cannot see coming from the preview.
+     *
+     * So the limit is resolved by the CALLER, from the connection, and passed IN
+     * — which is also what makes it part of what was approved rather than
+     * something decided later behind the approver's back. `withResolvedLimit()`
+     * is the supported way to do that, and a test pins that per-call rules beat
+     * declared ones.
+     */
     limit: number | null;
     unit: TextUnit;
     /**
@@ -1529,6 +1594,19 @@ declare function payloadHash(payload: RenderedPayload): Promise<string>;
  * every one of those checks from being hollow.
  */
 declare function isEmptyPayload(payload: RenderedPayload): boolean;
+/**
+ * Apply a per-connection limit over a connector's declared rules.
+ *
+ * The one supported way to do the thing `RenderRules.limit` insists on: a
+ * Mastodon instance publishes its own `max_toot_chars`, a Discord webhook does
+ * not, and the same connector serves both. Resolving happens at the call site,
+ * with the connection in hand, and the resolved value travels INTO `render` so
+ * it is part of the payload the approver saw.
+ *
+ * `undefined` keeps whatever the connector declared — "I did not look" is not
+ * the same as "there is no limit", and only the second is `null`.
+ */
+declare function withResolvedLimit(rules: RenderRules, limit: number | null | undefined): RenderRules;
 
 /**
  * The seam — two objects, deliberately separate.
@@ -1576,6 +1654,28 @@ declare function isEmptyPayload(payload: RenderedPayload): boolean;
  * path — and the reference implementation very nearly stored it as
  * configuration because it looked like a URL.
  */
+/**
+ * Who a credential belongs to.
+ *
+ * Exported as a runtime constant as well as a type — see `CREDENTIAL_SCOPES`.
+ */
+type CredentialScope = "provider" | "account";
+/**
+ * The scopes, as DATA.
+ *
+ * Because this union crosses a JSON boundary and the compiler cannot follow it
+ * there. When these values were renamed from `app`/`brand`, a consumer that
+ * re-declared the field shape on its client kept compiling — their
+ * `f.scope === "brand"` silently became never-true, and every credential field
+ * would have rendered as shared. `tsc` gives a host mirroring these types no
+ * help at all, so the values ship as data a host can validate against at the
+ * boundary where the compiler stops.
+ */
+declare const CREDENTIAL_SCOPES: readonly CredentialScope[];
+/** Severities, as data, for the same reason. */
+declare const PROBLEM_SEVERITIES: readonly ["block", "warn"];
+/** Canonical metric names, as data, for the same reason. */
+declare const CANONICAL_METRICS: readonly ["like", "share", "reply", "quote", "view"];
 type CredentialField = {
     /** Stable key. The host maps it to wherever it keeps values. */
     key: string;
@@ -1589,7 +1689,7 @@ type CredentialField = {
      * The distinction exists because getting it wrong means either asking for the
      * same app secret five times or letting one account's token reach another's.
      */
-    scope: "provider" | "account";
+    scope: CredentialScope;
     secret: boolean;
     required: boolean;
     /** A hint for an empty field. NEVER a real value. */
@@ -1642,8 +1742,26 @@ type ProviderAdapter = {
      * that anything can be revoked. "No known expiry" is not "cannot stop working".
      */
     credentialLifetimeDays?: number;
-    /** How the provider exposes a test estate, in the four shapes that exist. */
+    /**
+     * How the provider exposes a test estate.
+     *
+     * **`"unverified"` is a real answer and is the right one until somebody has
+     * actually checked.** Being wrong here points a workflow at a live estate
+     * while a person believes it is a test one, so the type carries "nobody
+     * looked" rather than forcing a guess — a comment saying so is not a type, and
+     * `providerProblems()` reports the combination `implemented: true` +
+     * `unverified`.
+     */
     sandbox: SandboxKind;
+    /**
+     * What `verify` proves, and what it does NOT.
+     *
+     * Required whenever `verify` exists, and checked by `providerProblems()`.
+     * Telegram's `getMe` validates the token and says nothing about whether the
+     * bot was added to the target chat — which is the step everyone actually gets
+     * stuck on. A green tick that means more than it should is worse than no tick.
+     */
+    proves?: string;
     /**
      * A read-only call proving the credential works AND reaches the right account.
      *
@@ -1860,6 +1978,22 @@ declare function capabilityProblems(connector: Connector<never>): string[];
  * `undefined` and non-numbers do not.
  */
 declare function reported(values: Record<string, unknown>): Record<string, number>;
+/**
+ * Every way a PROVIDER's declaration can outrun what anyone actually checked.
+ *
+ * The sibling of `capabilityProblems`, one level up. `capabilities.metrics: true`
+ * with no shape turns an unimplemented feature into a reported zero; the
+ * equivalent here turns *nobody looked* into a statement about a test estate —
+ * and that field is the one where being wrong sends a person to a live estate
+ * believing it is a test one.
+ *
+ * Strings rather than a throw, so a host reports all of them at once. A check
+ * that stops at the first problem trains people to fix one thing and re-run,
+ * which is how a list of six becomes six rounds.
+ */
+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;
 
 /**
  * Dry-verify — proving the transport with a credential that cannot work.
@@ -2126,4 +2260,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, CONNECTOR_API_VERSION, CONNECTOR_MODES, 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, 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, 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, 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, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, satisfiesMinimum, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac };
+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 };

package/dist/index.js

@@ -67,6 +67,8 @@ var AMBIGUOUS_CODES = /* @__PURE__ */ new Set([
 ]);
 var AMBIGUOUS_NAMES = /* @__PURE__ */ new Set(["AbortError", "TimeoutError"]);
 function classifyError(error) {
+  const attached = error?.classified;
+  if (attached && typeof attached === "object" && typeof attached.kind === "string") return attached;
   const detail = error instanceof Error ? error.message : String(error);
   const code = error?.code ?? error?.cause?.code ?? "";
   const name = error instanceof Error ? error.name : "";
@@ -304,19 +306,42 @@ function fakeRequest(service, operation, config, input) {
 
 // src/mode.ts
 var CONNECTOR_MODES = ["fake", "sandbox", "live"];
+var SANDBOX_KINDS = [
+  "credential",
+  "base-url",
+  "separate-account",
+  "restricted-reach",
+  "none",
+  "unverified"
+];
+var SELECTABLE_SANDBOX = /* @__PURE__ */ new Set([
+  "credential",
+  "base-url",
+  "separate-account"
+]);
+function sandboxIsSelectable(kind) {
+  return SELECTABLE_SANDBOX.has(kind);
+}
+function sandboxRefusal(service, kind) {
+  if (kind === "restricted-reach") {
+    return service + ` has no separate test estate. What it has instead is an ACCOUNT-LEVEL reach restriction - an unreviewed app that posts only to its own developers, or only privately. Same credentials, same endpoints, same estate: only the audience changes, and nothing in a request selects it. That makes it the sandbox shape most likely to be mistaken for a real one, because a restricted call looks exactly like a successful one - ok, a real id, and no audience. Use "fake" to develop without touching the provider, or "live" and confirm reach on the provider's own surface, which is the only place it is visible.`;
+  }
+  if (kind === "unverified") {
+    return "Nobody has verified what test estate " + service + ' offers, so "sandbox" cannot be honoured - the resolver would be guessing, and the cost of guessing wrong here is a workflow pointed at a live estate while somebody believes it is a test one. Find out and declare it, or use "fake".';
+  }
+  return service + ' has no sandbox estate, so "sandbox" cannot be honoured. Use "fake" to develop without credentials, or "live" to talk to the provider.';
+}
 function resolveConnectorMode(inputs) {
   const { requested, connectionMode, sandbox, hasSandboxCredentials, environment } = inputs;
   if (requested && requested !== "auto") {
-    if (requested === "sandbox" && sandbox === "none") {
-      throw new ConnectorModeError(
-        `This connector's provider has no sandbox estate, so "sandbox" cannot be honoured. Use "fake" to develop without credentials, or "live" to talk to the provider.`
-      );
+    if (requested === "sandbox" && !sandboxIsSelectable(sandbox)) {
+      throw new ConnectorModeError(sandboxRefusal("This connector's provider", sandbox));
     }
     return requested;
   }
   if (connectionMode) return connectionMode;
   if (environment.production) return "live";
-  return sandbox !== "none" && hasSandboxCredentials ? "sandbox" : "fake";
+  return sandboxIsSelectable(sandbox) && hasSandboxCredentials ? "sandbox" : "fake";
 }
 var ConnectorModeError = class extends Error {
   constructor(message) {
@@ -347,10 +372,8 @@ function connectionsFor(service) {
 function resolveConnection(options) {
   const { service, operation, sandbox } = options;
   const requestedMode = options.requested ?? "auto";
-  if (requestedMode === "sandbox" && sandbox === "none") {
-    throw new ConnectorModeError(
-      `${service} has no sandbox estate, so "sandbox" cannot be honoured. Use "fake" to develop without credentials, or "live" to talk to the provider.`
-    );
+  if (requestedMode === "sandbox" && !sandboxIsSelectable(sandbox)) {
+    throw new ConnectorModeError(sandboxRefusal(service, sandbox));
   }
   const id = options.connectionId?.trim() || service;
   if (options.credentials) {
@@ -877,6 +900,41 @@ function reported(values) {
   }
   return out;
 }
+function providerProblems(provider) {
+  const problems = [];
+  if (provider.implemented && provider.sandbox === "unverified") {
+    problems.push(
+      `${provider.id} says it is implemented while its sandbox shape is still "unverified". Something a person can run today must not be ambiguous about which estate it reaches \u2014 verify it, or set implemented: false.`
+    );
+  }
+  if (provider.implemented && provider.fields.length === 0) {
+    problems.push(`${provider.id} says it is implemented but declares no credential fields.`);
+  }
+  if (provider.implemented && provider.setup.length === 0) {
+    problems.push(
+      `${provider.id} says it is implemented and names no setup steps. The code is never the expensive part; the setup is, and a provider whose setup is undocumented is one nobody can stand up.`
+    );
+  }
+  for (const field of provider.fields) {
+    if (field.help.trim().length < 10) {
+      problems.push(`${provider.id}.${field.key} has no help text worth reading.`);
+    }
+  }
+  if (provider.verify && !provider.proves) {
+    problems.push(
+      `${provider.id} ships a verify but does not say what it PROVES. A green tick that means more than it should is worse than no tick \u2014 name the step it does not cover.`
+    );
+  }
+  if (provider.sandbox === "restricted-reach" && !provider.summary.toLowerCase().includes("reach")) {
+    problems.push(
+      `${provider.id} is declared restricted-reach and its summary never mentions reach. That shape looks exactly like a successful post nobody can see, so the surface has to say so before anyone runs it.`
+    );
+  }
+  return problems;
+}
+function providerSandboxIsSelectable(provider) {
+  return sandboxIsSelectable(provider.sandbox);
+}
 
 // src/probe.ts
 async function probe(spec) {
@@ -1078,6 +1136,14 @@ async function payloadHash(payload) {
 function isEmptyPayload(payload) {
   return payload.segments.every((segment) => segment.text.trim() === "");
 }
+function withResolvedLimit(rules, limit) {
+  return limit === void 0 ? rules : { ...rules, limit };
+}
+
+// src/seam.ts
+var CREDENTIAL_SCOPES = ["provider", "account"];
+var PROBLEM_SEVERITIES = ["block", "warn"];
+var CANONICAL_METRICS = ["like", "share", "reply", "quote", "view"];
 
 // src/webhook.ts
 async function verifyHmac(options) {
@@ -1179,8 +1245,10 @@ function hasDelivery(value) {
 }
 export {
   AMBIGUOUS_REFUSAL,
+  CANONICAL_METRICS,
   CONNECTOR_API_VERSION,
   CONNECTOR_MODES,
+  CREDENTIAL_SCOPES,
   ConnectorAmbiguous,
   ConnectorApiMismatch,
   ConnectorAuthError,
@@ -1197,8 +1265,10 @@ export {
   FAKE_EPOCH,
   MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING,
+  PROBLEM_SEVERITIES,
   RENDERER_VERSION,
   REVIEW_STALE_DAYS,
+  SANDBOX_KINDS,
   SUPPORTED_CONNECTOR_API,
   assertConnectorApi,
   byteRangeOf,
@@ -1230,6 +1300,8 @@ export {
   payloadHash,
   postChain,
   probe,
+  providerProblems,
+  providerSandboxIsSelectable,
   registerConnectionHost,
   registerTransport,
   render,
@@ -1241,6 +1313,8 @@ export {
   runIdentityFrom,
   runKeyFrom,
   runProbes,
+  sandboxIsSelectable,
+  sandboxRefusal,
   satisfiesMinimum,
   seedFrom,
   shapeOf,
@@ -1251,6 +1325,7 @@ export {
   unchecked,
   utf8Length,
   verifyDelivery,
-  verifyHmac
+  verifyHmac,
+  withResolvedLimit
 };
 //# sourceMappingURL=index.js.map