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

package/README.md

@@ -1,175 +1,200 @@
-# fancy-connector-core
-
-**The runtime under every Fancy connector.** Modes and estates, connections, one
-call path, a failure taxonomy that knows the difference between *it never
-arrived* and *nobody can tell*, deterministic fakers, webhook verification, pure
-versioned rendering, chain posting, declared metric shapes, credential-free
-probes, and API-drift reporting.
-
-Matched **TypeScript + PHP**, one repository, **zero runtime dependencies in
-either ecosystem**.
-
-```bash
-npm install @particle-academy/fancy-connector-core
-composer require particle-academy/fancy-connector-core
-```
-
----
-
-## It owns the wire. It never owns a gate.
-
-Approval, liveness, the approved-bytes comparison, consent, second review and
-every journal belong to the **host** — because each is enforced in one place and
-every connector inherits it from the host's dispatch path rather than
-implementing it.
-
-```ts
-await connector.call(target, { dryRun, credentials });
-//                              ^^^^^^  ^^^^^^^^^^^
-//                              yours   yours
-```
-
-Three of those promises are **tests**, not intentions:
-
-1. **Nothing here reads the environment.** No `process.env`, no `getenv`. Your
-   credential storage discipline — a gitignored file behind a whitelist, a secret
-   manager, Laravel config — stays yours, because the package cannot reach past
-   it.
-2. **Nothing here contacts a URL of its own.** No telemetry, no phone-home, no
-   default endpoint. Even the drift checker does not fetch: you fetch, and pass
-   the document in.
-3. **Nothing here retries an ambiguous failure** unless the connector declared
-   that repeating a request is harmless.
-
----
-
-## The one that matters: retry, without ever sending twice
-
-A network hiccup should not lose a call. A retry after a request that succeeded
-and whose response was lost is a **double write** — the exact failure an
-idempotency gate exists to prevent, arriving through the door marked
-*reliability*.
-
-Nearly every retry helper reconciles those the same way and loses: it catches an
-error, waits, and tries again, because from the caller's side all failures look
-alike.
-
-| what happened | did the provider receive it? | retry? |
-|---|---|---|
-| DNS failure, connection refused | **no** | always safe |
-| HTTP 429 / 5xx | **yes**, and it explicitly refused | safe — it says it did nothing |
-| timeout, abort, **anything unrecognised** | **unknown** | only where the connector is idempotent |
-| other 4xx | yes, and the answer was a real no | never |
-
-```ts
-import { classifyError, shouldRetry } from "@particle-academy/fancy-connector-core";
-
-shouldRetry(classifyError(err).kind, { idempotent: connector.delivery.idempotent });
-```
-
-`idempotent` defaults to **false**, and `delivery.why` must cite the mechanism —
-`Idempotency-Key`, or the absence of one — because `idempotent: true` is the one
-claim whose failure is a public duplicate.
-
----
-
-## Text, and two one-line bugs that ASCII hides
-
-```ts
-import { measure, linkRanges, sliceByteRange } from "@particle-academy/fancy-connector-core";
-
-measure("👍", "graphemes");   // 1   — "👍".length is 2
-linkRanges("👍 https://example.test");  // UTF-8 BYTE ranges, not char offsets
-```
-
-`ByteRange` is a **type**, producible only by a function that encoded the string.
-A character-offset implementation is correct for ASCII and silently corrupts the
-*link* on any post containing an emoji — the post looks fine and goes somewhere
-wrong.
-
----
-
-## Rendering: pure, versioned, honest about loss
-
-```ts
-const payload = render(copy, {
-  limit: 300, unit: "graphemes", thread: true, links: true, label: "Bluesky",
-});
-
-payload.segments;  // one entry per message; more than one means a thread
-payload.problems;  // what could NOT be fitted. Never silently applied.
-await payloadHash(payload);  // RENDERER_VERSION is INSIDE the hash
-```
-
-Show the payload before you approve it, recompute it at dispatch, refuse on
-mismatch. That is the only way "what was approved is what was sent" survives the
-existence of adaptation — and the renderer version being inside the hash is what
-stops it being checked separately and forgotten.
-
----
-
-## Threading
-
-```ts
-await postChain(payload.segments.map((s) => s.text), answering, post);
-```
-
-Root fixed at the top of the chain; parent advancing to whatever was just posted.
-Reverse them and every message attaches to the first — a fan, not a thread — and
-the provider's response looks identical either way. The post function is an
-**argument** so that is reachable by a test.
-
----
-
-## Probes: an auth error proves the transport
-
-A connector written from documentation can be wrong in three ways that look
-identical until a credential arrives: the URL is wrong, the request shape is
-wrong, or the error handling never runs. **All three are invisible to a fake
-server, because a fake server agrees with whatever your code does.**
-
-So call the real API with a deliberately invalid credential and require an
-auth-shaped refusal.
-
-- `authStatuses` is declared per provider — a Discord webhook answers `404` for
-  an unknown id, so 404 IS its auth answer.
-- **A 2xx is a failure.** The credential is reaching nothing.
-- **Offline is `skip`, never `fail`.** A check that goes red on a train gets
-  ignored, and is then worth nothing when it goes red for real.
-
----
-
-## Drift: it reports, it never adapts
-
-A connector's worst failure is silent — the provider changes its API and nothing
-says so until something breaks.
-
-**And the fix is not a connector that reshapes itself.** That connector cannot be
-reviewed, its behaviour depends on when it ran, and adaptation is only ever a
-guess at intent. So:
-
-> Drift reports. The provider decides. A person acts.
-
-Drift also never changes runtime behaviour: it runs out of band, and a check that
-failed a working call because a *document* changed would be a self-inflicted
-outage.
-
-What is checked is a narrow projection, not a diff — *for the operations this
-connector actually calls, do the path, method, sent fields and read fields still
-exist?* Where a provider publishes no spec (most do not), the fallback is a
-recorded shape: field **names** only.
-
-`outcome` is `clean` | `drifted` | **`unchecked`**. The third is never collapsed
-into the first — a checker that could not see is not a checker that saw nothing
-wrong.
-
----
-
-## Documentation
-
-- [`AGENTS.md`](./AGENTS.md) — the invariants, the traps, and what a change here
-  breaks.
-- `.ai/plans/fancy-connectors.md` in the envelope — the architecture, the
-  Socialite seam, the drift research, and every decision with its reason.
-
-MIT.
+# fancy-connector-core
+
+**The runtime under every Fancy connector.** Modes and estates, connections, one
+call path, a failure taxonomy that knows the difference between *it never
+arrived* and *nobody can tell*, deterministic fakers, webhook verification, pure
+versioned rendering, chain posting, declared metric shapes, credential-free
+probes, and API-drift reporting.
+
+Matched **TypeScript + PHP**, one repository, **zero runtime dependencies in
+either ecosystem**.
+
+```bash
+npm install @particle-academy/fancy-connector-core
+composer require particle-academy/fancy-connector-core
+```
+
+---
+
+## It owns the wire. It never owns a gate.
+
+Approval, liveness, the approved-bytes comparison, consent, second review and
+every journal belong to the **host** — because each is enforced in one place and
+every connector inherits it from the host's dispatch path rather than
+implementing it.
+
+```ts
+await connector.call(target, { dryRun, credentials });
+//                              ^^^^^^  ^^^^^^^^^^^
+//                              yours   yours
+```
+
+Three of those promises are **tests**, not intentions:
+
+1. **Nothing here reads the environment.** No `process.env`, no `getenv`. Your
+   credential storage discipline — a gitignored file behind a whitelist, a secret
+   manager, Laravel config — stays yours, because the package cannot reach past
+   it.
+2. **Nothing here contacts a URL of its own.** No telemetry, no phone-home, no
+   default endpoint. Even the drift checker does not fetch: you fetch, and pass
+   the document in.
+3. **Nothing here retries an ambiguous failure** unless the connector declared
+   that repeating a request is harmless.
+
+---
+
+## The one that matters: retry, without ever sending twice
+
+A network hiccup should not lose a call. A retry after a request that succeeded
+and whose response was lost is a **double write** — the exact failure an
+idempotency gate exists to prevent, arriving through the door marked
+*reliability*.
+
+Nearly every retry helper reconciles those the same way and loses: it catches an
+error, waits, and tries again, because from the caller's side all failures look
+alike.
+
+| what happened | did the provider receive it? | retry? |
+|---|---|---|
+| DNS failure, connection refused | **no** | always safe |
+| HTTP 429 / 5xx | **yes**, and it explicitly refused | safe — it says it did nothing |
+| timeout, abort, **anything unrecognised** | **unknown** | only where the connector is idempotent |
+| other 4xx | yes, and the answer was a real no | never |
+
+```ts
+import { classifyError, shouldRetry } from "@particle-academy/fancy-connector-core";
+
+shouldRetry(classifyError(err).kind, { idempotent: connector.delivery.idempotent });
+```
+
+`idempotent` defaults to **false**, and `delivery.why` must cite the mechanism —
+`Idempotency-Key`, or the absence of one — because `idempotent: true` is the one
+claim whose failure is a public duplicate.
+
+---
+
+## Text, and two one-line bugs that ASCII hides
+
+```ts
+import { measure, linkRanges, sliceByteRange } from "@particle-academy/fancy-connector-core";
+
+measure("👍", "graphemes");   // 1   — "👍".length is 2
+linkRanges("👍 https://example.test");  // UTF-8 BYTE ranges, not char offsets
+```
+
+`ByteRange` is a **type**, producible only by a function that encoded the string.
+A character-offset implementation is correct for ASCII and silently corrupts the
+*link* on any post containing an emoji — the post looks fine and goes somewhere
+wrong.
+
+---
+
+## Rendering: pure, versioned, honest about loss
+
+```ts
+const payload = render(copy, {
+  limit: 300, unit: "graphemes", thread: true, links: true, label: "Bluesky",
+});
+
+payload.segments;  // one entry per message; more than one means a thread
+payload.problems;  // what could NOT be fitted. Never silently applied.
+await payloadHash(payload);  // RENDERER_VERSION is INSIDE the hash
+```
+
+Show the payload before you approve it, recompute it at dispatch, refuse on
+mismatch. That is the only way "what was approved is what was sent" survives the
+existence of adaptation — and the renderer version being inside the hash is what
+stops it being checked separately and forgotten.
+
+---
+
+## Threading
+
+```ts
+await postChain(payload.segments.map((s) => s.text), answering, post);
+```
+
+Root fixed at the top of the chain; parent advancing to whatever was just posted.
+Reverse them and every message attaches to the first — a fan, not a thread — and
+the provider's response looks identical either way. The post function is an
+**argument** so that is reachable by a test.
+
+---
+
+## Probes: an auth error proves the transport
+
+A connector written from documentation can be wrong in three ways that look
+identical until a credential arrives: the URL is wrong, the request shape is
+wrong, or the error handling never runs. **All three are invisible to a fake
+server, because a fake server agrees with whatever your code does.**
+
+So call the real API with a deliberately invalid credential and require an
+auth-shaped refusal.
+
+- `authStatuses` is declared per provider — a Discord webhook answers `404` for
+  an unknown id, so 404 IS its auth answer.
+- **A 2xx is a failure.** The credential is reaching nothing.
+- **Offline is `skip`, never `fail`.** A check that goes red on a train gets
+  ignored, and is then worth nothing when it goes red for real.
+
+---
+
+## Drift: it reports, it never adapts
+
+A connector's worst failure is silent — the provider changes its API and nothing
+says so until something breaks.
+
+**And the fix is not a connector that reshapes itself.** That connector cannot be
+reviewed, its behaviour depends on when it ran, and adaptation is only ever a
+guess at intent. So:
+
+> Drift reports. The provider decides. A person acts.
+
+Drift also never changes runtime behaviour: it runs out of band, and a check that
+failed a working call because a *document* changed would be a self-inflicted
+outage.
+
+What is checked is a narrow projection, not a diff — *for the operations this
+connector actually calls, do the path, method, sent fields and read fields still
+exist?* Where a provider publishes no spec (most do not), the fallback is a
+recorded shape: field **names** only.
+
+`outcome` is `clean` | `drifted` | **`unchecked`**. The third is never collapsed
+into the first — a checker that could not see is not a checker that saw nothing
+wrong.
+
+---
+
+## Depend on this with an open range, not a caret
+
+```jsonc
+// package.json
+"@particle-academy/fancy-connector-core": ">=0.2.0 <2.0.0"
+```
+```jsonc
+// composer.json
+"particle-academy/fancy-connector-core": ">=0.2.0 <2.0.0"
+```
+
+**Not `^0.2.0`.** A caret on a `0.x` locks the MINOR — npm and Composer both read
+`^0.2.0` as `>=0.2.0 <0.3.0` — so the next release is out of range and
+**`npm update` reports success having installed nothing.** A resolver quietly
+keeping the old version is indistinguishable from a resolver that had nothing to
+do, which is why this is worth stating rather than leaving to convention.
+
+This package intends the open range: **pre-1.0 minors may change what a connector
+sees, and `CONNECTOR_API_VERSION` is what tells you when** — loudly, at
+registration, naming which side is behind. That is a stronger guarantee than a
+caret gives you, and it is the reason the caret is not needed here.
+
+The first consumer of this package pinned `^0.1.0` and would have missed 0.2.0
+entirely. That is the whole argument.
+
+## Documentation
+
+- [`AGENTS.md`](./AGENTS.md) — the invariants, the traps, and what a change here
+  breaks.
+- `.ai/plans/fancy-connectors.md` in the envelope — the architecture, the
+  Socialite seam, the drift research, and every decision with its reason.
+
+MIT.

package/dist/index.cjs

@@ -21,8 +21,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   AMBIGUOUS_REFUSAL: () => AMBIGUOUS_REFUSAL,
+  CANONICAL_METRICS: () => CANONICAL_METRICS,
   CONNECTOR_API_VERSION: () => CONNECTOR_API_VERSION,
   CONNECTOR_MODES: () => CONNECTOR_MODES,
+  CREDENTIAL_SCOPES: () => CREDENTIAL_SCOPES,
   ConnectorAmbiguous: () => ConnectorAmbiguous,
   ConnectorApiMismatch: () => ConnectorApiMismatch,
   ConnectorAuthError: () => ConnectorAuthError,
@@ -39,8 +41,10 @@ __export(src_exports, {
   FAKE_EPOCH: () => FAKE_EPOCH,
   MAX_IDEMPOTENCY_KEY_LENGTH: () => MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING: () => NO_IDEMPOTENCY_KEY_WARNING,
+  PROBLEM_SEVERITIES: () => PROBLEM_SEVERITIES,
   RENDERER_VERSION: () => RENDERER_VERSION,
   REVIEW_STALE_DAYS: () => REVIEW_STALE_DAYS,
+  SANDBOX_KINDS: () => SANDBOX_KINDS,
   SUPPORTED_CONNECTOR_API: () => SUPPORTED_CONNECTOR_API,
   assertConnectorApi: () => assertConnectorApi,
   byteRangeOf: () => byteRangeOf,
@@ -72,6 +76,8 @@ __export(src_exports, {
   payloadHash: () => payloadHash,
   postChain: () => postChain,
   probe: () => probe,
+  providerProblems: () => providerProblems,
+  providerSandboxIsSelectable: () => providerSandboxIsSelectable,
   registerConnectionHost: () => registerConnectionHost,
   registerTransport: () => registerTransport,
   render: () => render,
@@ -83,6 +89,8 @@ __export(src_exports, {
   runIdentityFrom: () => runIdentityFrom,
   runKeyFrom: () => runKeyFrom,
   runProbes: () => runProbes,
+  sandboxIsSelectable: () => sandboxIsSelectable,
+  sandboxRefusal: () => sandboxRefusal,
   satisfiesMinimum: () => satisfiesMinimum,
   seedFrom: () => seedFrom,
   shapeOf: () => shapeOf,
@@ -93,7 +101,8 @@ __export(src_exports, {
   unchecked: () => unchecked,
   utf8Length: () => utf8Length,
   verifyDelivery: () => verifyDelivery,
-  verifyHmac: () => verifyHmac
+  verifyHmac: () => verifyHmac,
+  withResolvedLimit: () => withResolvedLimit
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -166,6 +175,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 : "";
@@ -403,19 +414,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) {
@@ -446,10 +480,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) {
@@ -976,6 +1008,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) {
@@ -1177,6 +1244,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) {
@@ -1279,8 +1354,10 @@ function hasDelivery(value) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AMBIGUOUS_REFUSAL,
+  CANONICAL_METRICS,
   CONNECTOR_API_VERSION,
   CONNECTOR_MODES,
+  CREDENTIAL_SCOPES,
   ConnectorAmbiguous,
   ConnectorApiMismatch,
   ConnectorAuthError,
@@ -1297,8 +1374,10 @@ function hasDelivery(value) {
   FAKE_EPOCH,
   MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING,
+  PROBLEM_SEVERITIES,
   RENDERER_VERSION,
   REVIEW_STALE_DAYS,
+  SANDBOX_KINDS,
   SUPPORTED_CONNECTOR_API,
   assertConnectorApi,
   byteRangeOf,
@@ -1330,6 +1409,8 @@ function hasDelivery(value) {
   payloadHash,
   postChain,
   probe,
+  providerProblems,
+  providerSandboxIsSelectable,
   registerConnectionHost,
   registerTransport,
   render,
@@ -1341,6 +1422,8 @@ function hasDelivery(value) {
   runIdentityFrom,
   runKeyFrom,
   runProbes,
+  sandboxIsSelectable,
+  sandboxRefusal,
   satisfiesMinimum,
   seedFrom,
   shapeOf,
@@ -1351,6 +1434,7 @@ function hasDelivery(value) {
   unchecked,
   utf8Length,
   verifyDelivery,
-  verifyHmac
+  verifyHmac,
+  withResolvedLimit
 });
 //# sourceMappingURL=index.cjs.map