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

package/CHANGELOG.md

@@ -6,6 +6,69 @@ 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.15.0] - 2026-11-08
+
+### Added
+
+- **`SetupStep` says who does each step and what it yields.** New optional
+  fields, in both runtimes:
+  - `actor`: `person` (the default when absent) or `agent`; `SETUP_ACTORS` /
+    `Setup::ACTORS` ship it as data.
+  - `prompt`: what an agent is asked to do. Required for an agent step.
+  - `copy`: `[{label, value}]` values the person pastes somewhere, such as a
+    callback URL.
+  - `fields`: the credential keys the step yields.
+  - `done`: how the person knows the step is done.
+
+  PHP's `SetupStep` gains `fromArray()` / `toArray()`. Absent stays absent:
+  a field nobody wrote is omitted, never null.
+- **`renderSetup` / `Setup::render`: a connector's steps rendered for one
+  app.** `{{appUrl}}`, `{{appName}}` and `{{connector}}` are filled in every
+  text a person or an agent reads.
+  - Any other `{{...}}` is refused as `unknown-token`, so a person never
+    pastes a literal brace into a provider console.
+  - A token with no value, or an empty one, is refused as `missing-context`,
+    so a callback never becomes `/hooks/twilio`.
+  - `appUrl` loses one trailing slash first, and a value is never expanded
+    again.
+  - Held to `fixtures/setup-render/cases.json` in both runtimes.
+
+## [0.14.0] - 2026-11-07
+
+### Added
+
+- **`readWithCursor` / `CursorRead::read`: a read that resumes from a
+  HOST-HELD cursor, and pages.** It's for Gmail's `history.list` after a push,
+  and Drive's `changes.list` after a channel notification, where the delivery
+  says only that something moved. The package holds no state: the host stores
+  the cursor, passes it in, and persists `cursor.next` when the run succeeds.
+  - `next` is read ONLY from the LAST page: Gmail's `historyId` is the
+    mailbox's current one on every page.
+  - More than `page.maxPages` is refused as `cursor-overflow`, never a partial
+    read.
+  - The provider's `expiredStatus` (Gmail's 404) is refused as
+    `cursor-expired`. Every other failure is rethrown unchanged.
+  - No stored cursor is refused as `cursor-missing`, and the provider is not
+    called.
+  - A collected list that's absent is `[]`; one that isn't a list is
+    `bad-page`.
+  - Cursors are strings.
+  - A refusal carries the caller's `resyncQuery`.
+
+  The reasons ship as data (`CURSOR_READ_REASONS`, `CursorRead::REASONS`).
+  Both runtimes read `fixtures/cursor-read/cases.json`: 14 authored cases
+  against a scripted provider, every call compared.
+
+### Changed
+
+- The README and the npm description now say plainly that PHP apps install
+  the package with Composer.
+- `fixtures/jwt` gains rows 0015 to 0024: signature length, values at and
+  above the modulus, and valid RSA signatures over malformed PKCS#1 v1.5
+  blocks.
+
+`CONNECTOR_API_VERSION` is unchanged: everything here is optional.
+
 ## [0.13.0] - 2026-11-01
 
 ### Added

package/README.md

@@ -9,10 +9,15 @@ 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**.
+either ecosystem**. TypeScript and Node apps install it from npm; **PHP apps
+(Laravel included) install it with Composer**. Both packages are released
+together at the same version.
 
 ```bash
+# TypeScript / Node
 npm install @particle-academy/fancy-connector-core
+
+# PHP (Composer)
 composer require particle-academy/fancy-connector-core
 ```
 

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(src_exports, {
   CONNECTOR_API_VERSION: () => CONNECTOR_API_VERSION,
   CONNECTOR_MODES: () => CONNECTOR_MODES,
   CREDENTIAL_SCOPES: () => CREDENTIAL_SCOPES,
+  CURSOR_READ_REASONS: () => CURSOR_READ_REASONS,
   ConnectorAmbiguous: () => ConnectorAmbiguous,
   ConnectorApiMismatch: () => ConnectorApiMismatch,
   ConnectorAuthError: () => ConnectorAuthError,
@@ -36,6 +37,7 @@ __export(src_exports, {
   ConnectorRequestError: () => ConnectorRequestError,
   ConnectorTransient: () => ConnectorTransient,
   ConnectorUnreachable: () => ConnectorUnreachable,
+  CursorReadError: () => CursorReadError,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS: () => DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY: () => DEFAULT_RETRY,
   DELIVERY_DECODE_KINDS: () => DELIVERY_DECODE_KINDS,
@@ -53,8 +55,12 @@ __export(src_exports, {
   RENDERER_VERSION: () => RENDERER_VERSION,
   REVIEW_STALE_DAYS: () => REVIEW_STALE_DAYS,
   SANDBOX_KINDS: () => SANDBOX_KINDS,
+  SETUP_ACTORS: () => SETUP_ACTORS,
+  SETUP_RENDER_REASONS: () => SETUP_RENDER_REASONS,
+  SETUP_TOKENS: () => SETUP_TOKENS,
   SIGNED_URI_RULES: () => SIGNED_URI_RULES,
   SUPPORTED_CONNECTOR_API: () => SUPPORTED_CONNECTOR_API,
+  SetupRenderError: () => SetupRenderError,
   assertConnectorApi: () => assertConnectorApi,
   byteRangeOf: () => byteRangeOf,
   callConnector: () => callConnector,
@@ -104,9 +110,11 @@ __export(src_exports, {
   probe: () => probe,
   providerProblems: () => providerProblems,
   providerSandboxIsSelectable: () => providerSandboxIsSelectable,
+  readWithCursor: () => readWithCursor,
   registerConnectionHost: () => registerConnectionHost,
   registerTransport: () => registerTransport,
   render: () => render,
+  renderSetup: () => renderSetup,
   reported: () => reported,
   resetRateState: () => resetRateState,
   resolveConnection: () => resolveConnection,
@@ -302,10 +310,10 @@ var lastCallAt = /* @__PURE__ */ new Map();
 async function respectRate(channel, minIntervalMs, now = () => Date.now(), sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
   if (minIntervalMs <= 0) return { waitedMs: 0 };
   const previous = lastCallAt.get(channel);
-  const at = now();
-  const waitedMs = previous === void 0 ? 0 : Math.max(0, previous + minIntervalMs - at);
+  const at2 = now();
+  const waitedMs = previous === void 0 ? 0 : Math.max(0, previous + minIntervalMs - at2);
   if (waitedMs > 0) await sleep(waitedMs);
-  lastCallAt.set(channel, at + waitedMs);
+  lastCallAt.set(channel, at2 + waitedMs);
   return { waitedMs };
 }
 function resetRateState() {
@@ -803,6 +811,71 @@ function readString(config, key) {
   return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
 }
 
+// src/cursor-read.ts
+var CURSOR_READ_REASONS = ["cursor-missing", "cursor-expired", "cursor-overflow", "bad-page"];
+var CursorReadError = class extends Error {
+  constructor(reason, message, resyncQuery) {
+    super(message);
+    this.reason = reason;
+    this.resyncQuery = resyncQuery;
+    this.name = "CursorReadError";
+  }
+  reason;
+  resyncQuery;
+};
+async function readWithCursor(spec, cursor, call, options = {}) {
+  const refuse = (reason, message) => new CursorReadError(reason, message, options.resyncQuery);
+  const used = asCursor(cursor);
+  if (used === null) throw refuse("cursor-missing", `no stored ${spec.param}: the host seeds one before the first read`);
+  const collected = [];
+  let last;
+  let token = null;
+  let pages = 0;
+  for (; ; ) {
+    if (spec.page && pages === spec.page.maxPages) {
+      throw refuse("cursor-overflow", `more than ${spec.page.maxPages} pages since ${spec.param} ${used}`);
+    }
+    const params = { [spec.param]: used };
+    if (spec.page && token !== null) params[spec.page.param] = token;
+    try {
+      last = await call(params);
+    } catch (error) {
+      const status = error?.status;
+      if (spec.expiredStatus !== void 0 && status === spec.expiredStatus) {
+        throw refuse("cursor-expired", `${spec.param} ${used} is out of the provider's range (${status})`);
+      }
+      throw error;
+    }
+    pages++;
+    if (!spec.page) break;
+    const items = at(last, spec.page.collect);
+    if (items !== void 0 && !Array.isArray(items)) {
+      throw refuse("bad-page", `${spec.page.collect} is not a list`);
+    }
+    if (items) collected.push(...items);
+    token = asCursor(at(last, spec.page.from));
+    if (token === null) break;
+  }
+  const data = spec.page ? withList(last, spec.page.collect, collected) : last;
+  return { data, cursor: { used, next: asCursor(at(last, spec.advanceFrom)) } };
+}
+function asCursor(value) {
+  if (typeof value === "string") return value === "" ? null : value;
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return null;
+}
+function at(value, path) {
+  return path.split(".").reduce(
+    (v, key) => v !== null && typeof v === "object" && !Array.isArray(v) ? v[key] : void 0,
+    value
+  );
+}
+function withList(data, path, list) {
+  const [head, ...rest] = path.split(".");
+  const base = data !== null && typeof data === "object" && !Array.isArray(data) ? data : {};
+  return { ...base, [head]: rest.length ? withList(base[head], rest.join("."), list) : list };
+}
+
 // src/drift.ts
 function resolveRef(document, node, depth = 0) {
   if (depth > 8 || node === null || typeof node !== "object") return node;
@@ -1457,32 +1530,32 @@ function base64urlBytes(segment) {
 var EXPIRES_AT_UNITS = ["rfc3339", "epoch-ms"];
 var INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
 var DEFAULT_CONTEXT = { service: "", operation: "subscription" };
-function instantMs(value, field, at) {
+function instantMs(value, field, at2) {
   if (typeof value !== "string" || !INSTANT.test(value)) {
     throw new ConnectorConfigError(
       `${field} must be an RFC 3339 instant such as "2026-09-22T00:00:00Z", got ${JSON.stringify(value)}. A provider's own shape \u2014 Google's epoch milliseconds, say \u2014 is converted by the connector, never guessed at here.`,
-      at
+      at2
     );
   }
   const ms = Date.parse(value.replace(/(\.\d{3})\d+/, "$1"));
   if (Number.isNaN(ms)) {
-    throw new ConnectorConfigError(`${field} is not a real instant: ${JSON.stringify(value)}`, at);
+    throw new ConnectorConfigError(`${field} is not a real instant: ${JSON.stringify(value)}`, at2);
   }
   return ms;
 }
-function leaseFromResponse(declaration, response, at = DEFAULT_CONTEXT) {
+function leaseFromResponse(declaration, response, at2 = DEFAULT_CONTEXT) {
   const { expiresAtFrom: path, expiresAtUnit: unit } = declaration;
   if (!EXPIRES_AT_UNITS.includes(unit)) {
     throw new ConnectorConfigError(
       `expiresAtUnit must be one of ${EXPIRES_AT_UNITS.join(" | ")}, got ${JSON.stringify(unit)}.`,
-      at
+      at2
     );
   }
   const value = readPath(response, path);
   if (value === void 0 || value === null) {
     throw new ConnectorConfigError(
       `${path} is not present in the response, so no lease can be built \u2014 a subscription with no known expiry is one nobody renews.`,
-      at
+      at2
     );
   }
   let expiresAt;
@@ -1491,7 +1564,7 @@ function leaseFromResponse(declaration, response, at = DEFAULT_CONTEXT) {
     if (!Number.isSafeInteger(ms)) {
       throw new ConnectorConfigError(
         `${path} must be epoch milliseconds as digits under "epoch-ms", got ${JSON.stringify(value)}.`,
-        at
+        at2
       );
     }
     expiresAt = new Date(ms).toISOString();
@@ -1499,14 +1572,14 @@ function leaseFromResponse(declaration, response, at = DEFAULT_CONTEXT) {
     if (typeof value !== "string" || !INSTANT.test(value)) {
       throw new ConnectorConfigError(
         `${path} must be an RFC 3339 instant under "rfc3339", got ${JSON.stringify(value)}.`,
-        at
+        at2
       );
     }
-    expiresAt = new Date(instantMs(value, path, at)).toISOString();
+    expiresAt = new Date(instantMs(value, path, at2)).toISOString();
   }
   return subscriptionLease(
     { expiresAt, renewBeforeSeconds: declaration.renewBeforeSeconds, renewOperation: declaration.renewOperation },
-    at
+    at2
   );
 }
 function readPath(value, path) {
@@ -1517,18 +1590,18 @@ function readPath(value, path) {
   }
   return current;
 }
-function subscriptionLease(input, at = DEFAULT_CONTEXT) {
-  instantMs(input.expiresAt, "expiresAt", at);
+function subscriptionLease(input, at2 = DEFAULT_CONTEXT) {
+  instantMs(input.expiresAt, "expiresAt", at2);
   if (!Number.isInteger(input.renewBeforeSeconds) || input.renewBeforeSeconds <= 0) {
     throw new ConnectorConfigError(
       `renewBeforeSeconds must be a positive whole number of seconds, got ${JSON.stringify(input.renewBeforeSeconds)}. Zero would make the lease due only at the instant it expires, which is a lease nobody renews.`,
-      at
+      at2
     );
   }
   if (typeof input.renewOperation !== "string" || input.renewOperation.trim() === "") {
     throw new ConnectorConfigError(
       "renewOperation must name the operation the host calls when the lease is due; a due lease with nothing to call is one nobody renews.",
-      at
+      at2
     );
   }
   return { expiresAt: input.expiresAt, renewBeforeSeconds: input.renewBeforeSeconds, renewOperation: input.renewOperation };
@@ -1537,10 +1610,10 @@ function leaseRenewAt(lease) {
   return new Date(instantMs(lease.expiresAt, "expiresAt", DEFAULT_CONTEXT) - lease.renewBeforeSeconds * 1e3).toISOString();
 }
 function leaseState(lease, now) {
-  const at = now instanceof Date ? now.getTime() : instantMs(now, "now", DEFAULT_CONTEXT);
+  const at2 = now instanceof Date ? now.getTime() : instantMs(now, "now", DEFAULT_CONTEXT);
   const expires = instantMs(lease.expiresAt, "expiresAt", DEFAULT_CONTEXT);
-  if (at >= expires) return "expired";
-  if (at >= expires - lease.renewBeforeSeconds * 1e3) return "due";
+  if (at2 >= expires) return "expired";
+  if (at2 >= expires - lease.renewBeforeSeconds * 1e3) return "due";
   return "active";
 }
 function leaseAction(lease, now) {
@@ -1860,8 +1933,8 @@ function splitMultipart(body, boundary) {
   if (partStart >= 0 && partStart <= body.length) children.push(body.subarray(partStart));
   return children;
 }
-function startsWith(haystack, at, needle) {
-  for (let k = 0; k < needle.length; k++) if (haystack[at + k] !== needle[k]) return false;
+function startsWith(haystack, at2, needle) {
+  for (let k = 0; k < needle.length; k++) if (haystack[at2 + k] !== needle[k]) return false;
   return true;
 }
 function parseMime(raw) {
@@ -2428,6 +2501,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) {
@@ -2503,6 +2623,7 @@ function hasDelivery(value) {
   CONNECTOR_API_VERSION,
   CONNECTOR_MODES,
   CREDENTIAL_SCOPES,
+  CURSOR_READ_REASONS,
   ConnectorAmbiguous,
   ConnectorApiMismatch,
   ConnectorAuthError,
@@ -2514,6 +2635,7 @@ function hasDelivery(value) {
   ConnectorRequestError,
   ConnectorTransient,
   ConnectorUnreachable,
+  CursorReadError,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY,
   DELIVERY_DECODE_KINDS,
@@ -2531,8 +2653,12 @@ function hasDelivery(value) {
   RENDERER_VERSION,
   REVIEW_STALE_DAYS,
   SANDBOX_KINDS,
+  SETUP_ACTORS,
+  SETUP_RENDER_REASONS,
+  SETUP_TOKENS,
   SIGNED_URI_RULES,
   SUPPORTED_CONNECTOR_API,
+  SetupRenderError,
   assertConnectorApi,
   byteRangeOf,
   callConnector,
@@ -2582,9 +2708,11 @@ function hasDelivery(value) {
   probe,
   providerProblems,
   providerSandboxIsSelectable,
+  readWithCursor,
   registerConnectionHost,
   registerTransport,
   render,
+  renderSetup,
   reported,
   resetRateState,
   resolveConnection,