@particle-academy/fancy-connector-core 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,34 @@ 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.7.0] - 2026-09-15
+
+Two additions to the connector vocabulary, both approved by the owner on
+2026-09-14 and both meeting the two-provider bar before shipping: the
+subscription lease is for Google Calendar `events.watch` and Microsoft Graph
+subscriptions; the MIME transform is for inbound email, provider-agnostic,
+with Resend first.
+
+### Added
+
+- **`SubscriptionLease`** (`src/lease.ts`, `SubscriptionLease.php` with
+  `LeaseState` and `LeaseAction`) — the duty a `subscription` trigger carries,
+  as one value: the provider's expiry as an RFC 3339 instant, the connector's
+  `renewBeforeSeconds`, and the `renewOperation` the host calls when due.
+  `leaseState` says where it is (active / due / expired — both boundaries
+  inclusive, expired wins) and `leaseAction` what the host does (none / renew /
+  resync; a missed lease is resync, never a quiet re-create). Both runtimes
+  read `fixtures/subscription-lease/cases.json`. A host runs ONE renewal
+  scheduler for every expiring trigger instead of one per connector.
+- **`parseMime` / `Mime::parse`** — raw MIME in, `headers`, `subject`,
+  `messageId`, `text`, `html`, `parts` and `attachments` out, identical in both
+  runtimes and held to the authored corpus under `fixtures/mime/` (CRLF and
+  LF; folded headers; RFC 2047 B and Q words; quoted-printable and base64;
+  nested multipart; RFC 2231 `filename*`; utf-8, us-ascii, iso-8859-1,
+  iso-8859-15 and windows-1252 — any other charset leaves a part with no
+  text). Attachments carry their bytes as base64. **What to do:** nothing
+  unless you want them; neither touches an existing surface.
+
 ## [0.6.2] - 2026-09-14
 
 ### Fixed

package/dist/index.cjs

@@ -64,15 +64,19 @@ __export(src_exports, {
   fakeValues: () => fakeValues,
   getConnectionHost: () => getConnectionHost,
   graphemes: () => graphemes,
-  header: () => header,
+  header: () => header2,
   hmac: () => hmac,
   httpFailure: () => httpFailure,
   idempotencyKeyFor: () => idempotencyKeyFor,
   isEmptyPayload: () => isEmptyPayload,
   isRemote: () => isRemote,
   isUnconditionallyRetryable: () => isUnconditionallyRetryable,
+  leaseAction: () => leaseAction,
+  leaseRenewAt: () => leaseRenewAt,
+  leaseState: () => leaseState,
   linkRanges: () => linkRanges,
   measure: () => measure,
+  parseMime: () => parseMime,
   payloadHash: () => payloadHash,
   postChain: () => postChain,
   probe: () => probe,
@@ -97,6 +101,7 @@ __export(src_exports, {
   shouldRetry: () => shouldRetry,
   sliceByteRange: () => sliceByteRange,
   splitToFit: () => splitToFit,
+  subscriptionLease: () => subscriptionLease,
   triggerEvent: () => triggerEvent,
   unchecked: () => unchecked,
   utf8Length: () => utf8Length,
@@ -703,21 +708,21 @@ async function prepare(service, connection, options) {
 }
 function encodeForm(form) {
   const pairs = [];
-  const walk = (prefix, value) => {
+  const walk2 = (prefix, value) => {
     if (value === void 0 || value === null) return;
     if (Array.isArray(value)) {
-      value.forEach((item, index) => walk(`${prefix}[${index}]`, item));
+      value.forEach((item, index) => walk2(`${prefix}[${index}]`, item));
       return;
     }
     if (typeof value === "object") {
       for (const [key, nested] of Object.entries(value)) {
-        walk(prefix === "" ? key : `${prefix}[${key}]`, nested);
+        walk2(prefix === "" ? key : `${prefix}[${key}]`, nested);
       }
       return;
     }
     pairs.push(`${encodeURIComponent(prefix)}=${encodeURIComponent(String(value))}`);
   };
-  walk("", form);
+  walk2("", form);
   return pairs.join("&");
 }
 var fetchTransport = async (request) => {
@@ -1021,6 +1026,59 @@ function fnv1a(value) {
   return hash.toString(16).padStart(8, "0");
 }
 
+// src/lease.ts
+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) {
+  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
+    );
+  }
+  const ms = Date.parse(value);
+  if (Number.isNaN(ms)) {
+    throw new ConnectorConfigError(`${field} is not a real instant: ${JSON.stringify(value)}`, at);
+  }
+  return ms;
+}
+function subscriptionLease(input, at = DEFAULT_CONTEXT) {
+  instantMs(input.expiresAt, "expiresAt", at);
+  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
+    );
+  }
+  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
+    );
+  }
+  return { expiresAt: input.expiresAt, renewBeforeSeconds: input.renewBeforeSeconds, renewOperation: input.renewOperation };
+}
+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 expires = instantMs(lease.expiresAt, "expiresAt", DEFAULT_CONTEXT);
+  if (at >= expires) return "expired";
+  if (at >= expires - lease.renewBeforeSeconds * 1e3) return "due";
+  return "active";
+}
+function leaseAction(lease, now) {
+  switch (leaseState(lease, now)) {
+    case "active":
+      return "none";
+    case "due":
+      return "renew";
+    case "expired":
+      return "resync";
+  }
+}
+
 // src/metrics.ts
 function compareShape(connectorId, declared, produced) {
   const declaredKeys = new Set((declared ?? []).map((metric) => metric.key));
@@ -1115,6 +1173,245 @@ function providerSandboxIsSelectable(provider) {
   return sandboxIsSelectable(provider.sandbox);
 }
 
+// src/mime.ts
+var CR = 13;
+var LF = 10;
+function latin1(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return s;
+}
+function bytesOfLatin1(s) {
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i) & 255;
+  return out;
+}
+function splitEntity(bytes) {
+  for (let i = 0; i < bytes.length; i++) {
+    if (bytes[i] === LF) {
+      if (bytes[i + 1] === LF) return [i, i + 2];
+      if (bytes[i + 1] === CR && bytes[i + 2] === LF) return [i, i + 3];
+    }
+  }
+  return [bytes.length, bytes.length];
+}
+function parseHeaders(block) {
+  const lines = block.split(/\r?\n/);
+  const unfolded = [];
+  for (const line of lines) {
+    if (line === "") continue;
+    if ((line.startsWith(" ") || line.startsWith("	")) && unfolded.length > 0) {
+      unfolded[unfolded.length - 1] += " " + line.trim();
+    } else {
+      unfolded.push(line);
+    }
+  }
+  const headers = [];
+  for (const line of unfolded) {
+    const colon = line.indexOf(":");
+    if (colon <= 0) continue;
+    headers.push({ name: line.slice(0, colon).trim().toLowerCase(), value: decodeWords(line.slice(colon + 1).trim()) });
+  }
+  return headers;
+}
+function header(headers, name) {
+  return headers.find((h) => h.name === name)?.value ?? null;
+}
+var ENCODED_WORD = /=\?([^?\s]+)\?([BbQq])\?([^?\s]*)\?=/g;
+function decodeWords(value) {
+  const joined = value.replace(/(\?=)[ \t\r\n]+(=\?)/g, "$1$2");
+  return joined.replace(ENCODED_WORD, (whole, charset, encoding, text) => {
+    const bytes = encoding.toUpperCase() === "B" ? base64Bytes(text) : bytesOfLatin1(text.replace(/_/g, " ").replace(/=([0-9A-Fa-f]{2})/g, (_m, h) => String.fromCharCode(parseInt(h, 16))));
+    const decoded = decodeCharset(bytes, charset);
+    return decoded ?? whole;
+  });
+}
+function parseParams(value) {
+  const [head, ...rest] = value.split(";");
+  const params = {};
+  const continued = {};
+  for (const piece of rest) {
+    const eq = piece.indexOf("=");
+    if (eq < 0) continue;
+    let key = piece.slice(0, eq).trim().toLowerCase();
+    let raw = piece.slice(eq + 1).trim();
+    if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) raw = raw.slice(1, -1).replace(/\\(.)/g, "$1");
+    const segment = /^(.+?)\*(\d+)(\*)?$/.exec(key);
+    if (segment) {
+      const [, base, n, star] = segment;
+      (continued[base] ??= [])[Number(n)] = star ? decode2231(raw, Number(n) === 0) : raw;
+      continue;
+    }
+    if (key.endsWith("*")) {
+      key = key.slice(0, -1);
+      params[key] = decode2231(raw, true);
+      continue;
+    }
+    params[key] ??= raw;
+  }
+  for (const [base, parts] of Object.entries(continued)) params[base] = parts.join("");
+  return { main: (head ?? "").trim().toLowerCase(), params };
+}
+var pendingCharset2231 = "utf-8";
+function decode2231(raw, first) {
+  let text = raw;
+  if (first) {
+    const m = /^([^']*)'[^']*'(.*)$/s.exec(raw);
+    if (m) {
+      pendingCharset2231 = m[1] || "utf-8";
+      text = m[2];
+    }
+  }
+  const bytes = bytesOfLatin1(text.replace(/%([0-9A-Fa-f]{2})/g, (_m, h) => String.fromCharCode(parseInt(h, 16))));
+  return decodeCharset(bytes, pendingCharset2231) ?? text;
+}
+function base64Bytes(text) {
+  return new Uint8Array(Buffer.from(text.replace(/[^A-Za-z0-9+/=]/g, ""), "base64"));
+}
+function quotedPrintableBytes(bytes) {
+  const out = [];
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    if (b !== 61) {
+      out.push(b);
+      continue;
+    }
+    const a = bytes[i + 1];
+    const c = bytes[i + 2];
+    if (a === LF) {
+      i += 1;
+      continue;
+    }
+    if (a === CR && c === LF) {
+      i += 2;
+      continue;
+    }
+    if (a !== void 0 && c !== void 0 && isHex(a) && isHex(c)) {
+      out.push(parseInt(String.fromCharCode(a, c), 16));
+      i += 2;
+      continue;
+    }
+    out.push(b);
+  }
+  return new Uint8Array(out);
+}
+function isHex(b) {
+  return b >= 48 && b <= 57 || b >= 65 && b <= 70 || b >= 97 && b <= 102;
+}
+function transferDecode(body, encoding) {
+  switch ((encoding ?? "7bit").trim().toLowerCase()) {
+    case "base64":
+      return base64Bytes(latin1(body));
+    case "quoted-printable":
+      return quotedPrintableBytes(body);
+    default:
+      return body;
+  }
+}
+function decodeCharset(bytes, charset) {
+  switch (charset.trim().toLowerCase()) {
+    case "utf-8":
+    case "utf8":
+      return new TextDecoder("utf-8").decode(bytes);
+    case "us-ascii":
+    case "ascii":
+    case "iso-8859-1":
+    case "latin1":
+      return Buffer.from(bytes).toString("latin1");
+    case "windows-1252":
+    case "cp1252":
+      return new TextDecoder("windows-1252").decode(bytes);
+    case "iso-8859-15":
+    case "latin9":
+      return new TextDecoder("iso-8859-15").decode(bytes);
+    default:
+      return null;
+  }
+}
+function walk(bytes, entityHeaders, acc) {
+  const [headerEnd, bodyStart] = splitEntity(bytes);
+  const headers = entityHeaders ?? parseHeaders(latin1(bytes.subarray(0, headerEnd)));
+  const body = bytes.subarray(entityHeaders ? 0 : bodyStart);
+  const type = parseParams(header(headers, "content-type") ?? "text/plain");
+  if (type.main.startsWith("multipart/") && type.params.boundary) {
+    for (const child of splitMultipart(body, type.params.boundary)) walk(child, null, acc);
+    return;
+  }
+  const disposition = parseParams(header(headers, "content-disposition") ?? "");
+  const decoded = transferDecode(body, header(headers, "content-transfer-encoding"));
+  const declaredDisposition = disposition.main === "attachment" || disposition.main === "inline" ? disposition.main : null;
+  const filename = disposition.params.filename ?? type.params.name ?? null;
+  const contentId = header(headers, "content-id")?.replace(/^<|>$/g, "") ?? null;
+  const isText = type.main.startsWith("text/");
+  const isAttachment = declaredDisposition === "attachment" || !isText;
+  const part = {
+    index: acc.parts.length,
+    contentType: type.main,
+    charset: type.params.charset?.toLowerCase() ?? null,
+    disposition: declaredDisposition,
+    filename,
+    contentId,
+    size: decoded.length,
+    headers
+  };
+  acc.parts.push(part);
+  if (isAttachment) {
+    acc.attachments.push({ ...part, content: Buffer.from(decoded).toString("base64") });
+    return;
+  }
+  const text = decodeCharset(decoded, type.params.charset ?? "utf-8");
+  if (text === null) return;
+  if (type.main === "text/plain" && acc.text === null) acc.text = text;
+  if (type.main === "text/html" && acc.html === null) acc.html = text;
+}
+function splitMultipart(body, boundary) {
+  const delimiter = bytesOfLatin1(`--${boundary}`);
+  const children = [];
+  let partStart = -1;
+  for (let i = 0; i <= body.length - delimiter.length; i++) {
+    if (i !== 0 && body[i - 1] !== LF) continue;
+    if (!startsWith(body, i, delimiter)) continue;
+    let partEnd = i;
+    if (partEnd > 0 && body[partEnd - 1] === LF) partEnd -= 1;
+    if (partEnd > 0 && body[partEnd - 1] === CR) partEnd -= 1;
+    if (partStart >= 0) children.push(body.subarray(partStart, partEnd));
+    let j = i + delimiter.length;
+    const closing = body[j] === 45 && body[j + 1] === 45;
+    if (closing) return children;
+    while (j < body.length && body[j] !== LF) j++;
+    partStart = j + 1;
+    i = j;
+  }
+  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;
+  return true;
+}
+function parseMime(raw) {
+  const bytes = typeof raw === "string" ? new Uint8Array(Buffer.from(raw, "utf8")) : raw;
+  const [headerEnd, bodyStart] = splitEntity(bytes);
+  const headers = parseHeaders(latin1(bytes.subarray(0, headerEnd)));
+  const body = bytes.subarray(bodyStart);
+  const acc = { parts: [], attachments: [], text: null, html: null };
+  const type = parseParams(header(headers, "content-type") ?? "text/plain");
+  if (type.main.startsWith("multipart/") && type.params.boundary) {
+    for (const child of splitMultipart(body, type.params.boundary)) walk(child, null, acc);
+  } else {
+    walk(body, headers.filter((h) => h.name.startsWith("content-")), acc);
+  }
+  return {
+    headers,
+    subject: header(headers, "subject"),
+    messageId: header(headers, "message-id"),
+    text: acc.text,
+    html: acc.html,
+    parts: acc.parts,
+    attachments: acc.attachments
+  };
+}
+
 // src/probe.ts
 async function probe(spec) {
   let response;
@@ -1374,7 +1671,7 @@ function constantTimeEquals(a, b) {
   for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
   return diff === 0;
 }
-function header(headers, name) {
+function header2(headers, name) {
   const wanted = name.toLowerCase();
   for (const [key, value] of Object.entries(headers)) {
     if (key.toLowerCase() !== wanted) continue;
@@ -1392,9 +1689,9 @@ async function verifyDelivery(trigger, delivery, secret, now) {
       reason: `${trigger.service}.${trigger.operation} declares no signature scheme, so a delivery cannot be trusted.`
     };
   }
-  const rawHeader = header(delivery.headers, spec.signatureHeader);
+  const rawHeader = header2(delivery.headers, spec.signatureHeader);
   const parsed = spec.parse && rawHeader ? spec.parse(rawHeader) : { signature: rawHeader };
-  const timestamp = parsed.timestamp ?? (spec.timestampHeader ? header(delivery.headers, spec.timestampHeader) : void 0);
+  const timestamp = parsed.timestamp ?? (spec.timestampHeader ? header2(delivery.headers, spec.timestampHeader) : void 0);
   return verifyHmac({
     raw: delivery.raw,
     signature: parsed.signature,
@@ -1475,8 +1772,12 @@ function hasDelivery(value) {
   isEmptyPayload,
   isRemote,
   isUnconditionallyRetryable,
+  leaseAction,
+  leaseRenewAt,
+  leaseState,
   linkRanges,
   measure,
+  parseMime,
   payloadHash,
   postChain,
   probe,
@@ -1501,6 +1802,7 @@ function hasDelivery(value) {
   shouldRetry,
   sliceByteRange,
   splitToFit,
+  subscriptionLease,
   triggerEvent,
   unchecked,
   utf8Length,