@particle-academy/fancy-connector-core 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -6,8 +6,120 @@ All notable changes to `fancy-connector-core` are documented here, in
 **This package is pre-1.0, so breaking changes land in MINOR releases.** The
 version number is not a promise it can keep yet; the entries below are.
 
+## [0.3.0] - 2026-08-19
+
+### Fixed
+
+- **`ECONNRESET` and `EPIPE` are `ambiguous`, not `unreachable`. This was a live
+  duplicate-send hazard.** Both were listed as codes proving the request never
+  left. They do not. A peer sends RST whenever it tears the connection down,
+  *including after it has received and acted on the request but before the
+  response comes back*; `EPIPE` is the same story from our side. Node surfaces
+  the safe case and the unsafe case as the same code, so the code cannot carry
+  the claim.
+
+  Because `shouldRetry` returns true for `unreachable` **without consulting
+  `idempotent`**, a reset produced up to three sends of a connector that had
+  explicitly declared `idempotent: false`. For a consumer publishing to social
+  networks that is a second public post that cannot be withdrawn.
+
+  This is the same defect as the 5xx / thrown-transport split fixed earlier, and
+  it contradicted this module's own stated rule -- *"an unknown failure treated
+  as unreachable would be retried, and the one thing worse than a lost send is
+  two sends nobody approved."* The two codes were standing exceptions to a rule
+  that should have covered them.
+
+  **What a consumer must DO:** nothing, if your connectors declare `idempotent`
+  honestly -- the fix only removes retries that were never safe. If you have a
+  connector marked `idempotent: true` that is not actually safe to repeat, this
+  release does not save you; that field is still load-bearing. If you were
+  relying on resets being retried for a genuinely idempotent connector, they
+  still are: `ambiguous` retries when `idempotent: true`.
+
+  `ECONNREFUSED`, `ENOTFOUND`, `EAI_AGAIN`, `EHOSTUNREACH` and `ENETUNREACH`
+  stay `unreachable` -- they do prove nothing was delivered -- and a test now
+  pins them there so the fix cannot overcorrect.
+
+  Found by a consumer's conformance fixture disagreeing with the core on its
+  first run, with a reproduction.
+
 ## [Unreleased]
 
+## [0.2.0] — unreleased
+
+The reference consumer migrated five adapters onto `0.1.0`, ran its acceptance
+suite, and filed four findings. All four were cases where the type or the
+classifier was *safe* and still *wrong* — the hardest kind to notice from inside,
+because nothing fails.
+
+### Fixed
+
+- **`classifyError` ignored the classification `httpFailure` attached.** It
+  re-derived from scratch, found no error code, and answered `ambiguous`
+  ("nobody can tell") for a `400` the provider had been explicit about.
+  **This was never a retry bug** — `deliver()` reads `error.classified` first and
+  only falls back — but a host that calls the exported classifier directly, which
+  is a reasonable thing to do, was told nobody could tell. The **PHP twin already
+  did this**, so the two runtimes disagreed. **What a consumer must do: nothing,
+  unless you asserted the old answer.** If you pinned `classifyError` on an
+  `httpFailure` to `ambiguous`, that assertion now reads `rejected` or
+  `refused-explicitly` — which is the answer you wanted.
+
+### Changed
+
+- **BREAKING (types only): `ChainRef` is `object`, was
+  `Record<string, string | number>`.** An ordinary interface does not satisfy an
+  index signature unless it declares one, so `interface PostRef { uri; cid }` did
+  **not** satisfy the old constraint — and the only other fix was to add an index
+  signature to a type used across a codebase in order to please a generic used in
+  one place. The reference consumer worked around it with `postChain<T & ChainRef>`
+  and two `as unknown as` casts, and could not use `ChainOutcome<T>` in its own
+  signatures at all. **What a consumer must do: delete the casts.** A constraint
+  everyone casts past is not enforcing anything.
+
+### Added
+
+- **`SandboxKind` gained `restricted-reach`** — the fifth shape, and the
+  dangerous one. A Meta app in Development Mode, an unaudited TikTok app that can
+  only post `SELF_ONLY`: same credentials, same endpoints, same estate, and only
+  the **audience** restricted. That is none of the previous four, and `none` —
+  which is what it was being forced into — is actively wrong. 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.
+- **`SandboxKind` gained `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. A comment saying so is not a
+  type.
+- **`sandboxIsSelectable()` / `sandboxRefusal()`** (`SandboxKind::isSelectable()`
+  / `->refusal()` in PHP). Auto-resolution no longer picks "sandbox" for anything
+  that cannot be selected, and each refusal explains **its own** reason —
+  collapsing the three into "no sandbox available" would hide the one that
+  matters.
+- **`providerProblems()`** — the sibling of `capabilityProblems()`, one level up.
+  Reports `implemented: true` with `sandbox: "unverified"`, a `verify` that does
+  not say what it **proves**, a `restricted-reach` provider whose summary never
+  mentions reach, and empty fields or setup on something claimed to be
+  implemented.
+- **`ProviderAdapter.proves`** — what a verify does NOT cover, declared on the
+  adapter as well as on each result, so a surface can say it *before* anyone runs
+  the check.
+- **`withResolvedLimit(rules, limit)`** — the supported way to resolve a
+  per-connection limit. A Mastodon instance publishes its own `max_toot_chars`;
+  baking a limit into a connector renders to 500 on an instance allowing 5000, or
+  to 5000 on one allowing 500, and both fail silently. `undefined` keeps the
+  declared limit, because *"I did not look"* is not *"there is no limit"* — and
+  `null` is a real answer meaning **uncounted**.
+- **`CREDENTIAL_SCOPES`, `SANDBOX_KINDS`, `PROBLEM_SEVERITIES`,
+  `CANONICAL_METRICS`** — every string union that crosses a JSON boundary now
+  ships as **data** as well as a type. The compiler cannot follow a type across
+  JSON: when `scope` was renamed from `app`/`brand`, a consumer re-declaring the
+  field shape on its client kept compiling and its `scope === "brand"` silently
+  became never-true, so every credential field would have rendered as shared.
+  (PHP had this for free — an enum is runtime data, and `tryFrom` fails loudly on
+  a value nobody serves any more.)
+
+
 ## [0.1.0] — unreleased
 
 First cut. Extracted and generalised from the `_connector` shared runtime in the
@@ -99,5 +211,6 @@ clock; this package is the runtime it is written on.
   satisfies it with no dependency in either direction and a host that has never
   heard of a workflow engine can implement it.
 
-[Unreleased]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/Particle-Academy/fancy-connector-core/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/Particle-Academy/fancy-connector-core/releases/tag/v0.1.0

package/README.md

@@ -165,6 +165,31 @@ 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

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);
 
@@ -149,16 +158,33 @@ function satisfiesMinimum(coreVersion, minimum) {
 
 // src/delivery.ts
 var UNREACHABLE_CODES = /* @__PURE__ */ new Set([
+  // Every code here must PROVE the request never reached an application:
+  // nothing listening, no route, or a name that never resolved. If a code can
+  // also occur after the peer received and acted on the request, it belongs in
+  // AMBIGUOUS_CODES -- `shouldRetry` retries `unreachable` without consulting
+  // `idempotent`, so a wrong entry here is a duplicate send, not a slow one.
   "ECONNREFUSED",
   "ENOTFOUND",
   "EAI_AGAIN",
   "EHOSTUNREACH",
   "ENETUNREACH",
-  "ECONNRESET",
-  "EPIPE",
   "ERR_SOCKET_CONNECTION_TIMEOUT"
 ]);
 var AMBIGUOUS_CODES = /* @__PURE__ */ new Set([
+  // A peer sends RST whenever it tears the connection down -- INCLUDING after
+  // it has received and acted on the request but before the response comes
+  // back. EPIPE is the same story from our side: we wrote to a socket the peer
+  // had already closed, and whether an earlier complete request was processed
+  // first is not knowable from here. Node surfaces the safe case and the unsafe
+  // case as the same code, so the code cannot carry the claim.
+  //
+  // These two sat in UNREACHABLE_CODES until 0.3.0, which made them
+  // unconditionally retryable and produced three sends of connectors that had
+  // declared `idempotent: false`. Same defect as the 5xx / thrown-transport
+  // split this module already fixed once, and a stated exception to a rule that
+  // should have covered them.
+  "ECONNRESET",
+  "EPIPE",
   "ETIMEDOUT",
   "UND_ERR_HEADERS_TIMEOUT",
   "UND_ERR_BODY_TIMEOUT",
@@ -166,6 +192,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 +431,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 +497,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 +1025,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 +1261,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 +1371,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 +1391,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 +1426,8 @@ function hasDelivery(value) {
   payloadHash,
   postChain,
   probe,
+  providerProblems,
+  providerSandboxIsSelectable,
   registerConnectionHost,
   registerTransport,
   render,
@@ -1341,6 +1439,8 @@ function hasDelivery(value) {
   runIdentityFrom,
   runKeyFrom,
   runProbes,
+  sandboxIsSelectable,
+  sandboxRefusal,
   satisfiesMinimum,
   seedFrom,
   shapeOf,
@@ -1351,6 +1451,7 @@ function hasDelivery(value) {
   unchecked,
   utf8Length,
   verifyDelivery,
-  verifyHmac
+  verifyHmac,
+  withResolvedLimit
 });
 //# sourceMappingURL=index.cjs.map