@zapier/kitcore 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @zapier/kitcore
 
+## 0.20.0
+
+### Minor Changes
+
+- 4b9d735: `createSdk` now checks that each id's providers match the contract its reference
+  declared, not only that a provider exists. A graph joined by string id used to
+  compile on the strength of the string alone, so a provider whose types
+  contradicted the reference reached the consumer and broke at runtime.
+
+  ```ts
+  const doubleRef = declareMethod<"double", { value: number }, number>({
+    id: "double",
+  });
+  // Written for a display surface: it formats instead of computing.
+  const formatsIt = defineMethod({
+    name: "double",
+    run: ({ input }: { input: { value: number } }) => `${input.value * 2}`,
+  });
+  // Compiled clean before. Rejected at createSdk now.
+  ```
+
+  A provider may accept **wider** input and must return a **subtype** of the
+  declared output, since the comparison is on the call a consumer makes. See the
+  kitcore README for how this applies to optional references, module references,
+  and `declareDefault`.
+
+  `selectExports` and `omitExports` now forward their source's ledgers. They
+  returned a bare aggregate before, which dropped both the requirements and the
+  contract ledger for everything behind them, so a head that reached a module
+  through either helper got no graph checking at all.
+
+  **Both changes can surface an error in a graph that compiled before.** That is
+  the point, since the mismatch was already there. Correct the provider, or widen
+  the reference to what the provider actually offers.
+
+  This release also fixes a latent problem with nested plugins. The cost of
+  checking a graph grew exponentially with aggregate nesting depth, and with the
+  length of a method import chain. Deep enough composition failed to compile at
+  all, reporting `error TS2589`. Both are close to linear now, so nesting and
+  chaining stay affordable.
+
+  Contract checking itself is new work, and it grows the declaration files a
+  package publishes. Every downstream typecheck and editor pays that cost.
+
+  **A hand-written annotation must be updated to keep its check.** `LeafSummary`
+  now requires the surfaced binding as a fourth argument, so a three-argument use
+  is a compile error. A `PluginSummary` written with two arguments still compiles
+  and declares no contract, which drops that plugin out of the check silently.
+
+  Added `ContractEntry`, `MethodContract`, `DeclarationSummary`, and
+  `OptionalDeclarationSummary`, for annotating a plugin by hand instead of letting
+  `define*` infer it.
+
+## 0.19.0
+
+### Minor Changes
+
+- 1ec9410: Added `RetryHttpRequestOptions.onRetry` and exported `RetryHttpRequestAttempt` for observing retries scheduled by `retryHttpRequestPlugin`. The callback runs before the retry wait and receives the request, operation ID, failed attempt number, selected delay, and response or error. Promise results are not awaited, and thrown errors or rejected promises do not cancel the retry. When a response is present, read only its status and headers.
+
+### Patch Changes
+
+- 1ec9410: `retryHttpRequestPlugin` now waits at least 100 milliseconds before retrying when generated backoff is capped by a zero or near-zero `maxDelayMilliseconds`. Use `maxAttempts: 1` to disable retries.
+
 ## 0.18.0
 
 ### Minor Changes

package/README.md

@@ -454,6 +454,51 @@ Two flavors, by what happens when nothing provides the id:
 - **Required** (`declareMethod` / `declareProperty`): an unsatisfied reference is a **compile-time** error (with a runtime backstop). Use when the capability must be present.
 - **Optional** (`declareOptionalProperty` / `declareOptionalMethod`): binds `undefined` instead of failing, so the consumer handles absence in code (`{ ...DEFAULTS, ...imports.config }` for a value, `imports.track?.(...)` for a method). Use to reference a _foreign_ capability userland may or may not import, without claiming its slot.
 
+### The contract is checked, not just the id
+
+`createSdk` checks that each id's providers match the contract the reference declared, not only that a provider exists. The comparison is on the call a consumer makes, so a provider may accept **wider** input and must return a **subtype** of the declared output. A provider written from scratch is checked the same as one written against the reference.
+
+```ts
+const doubleRef = declareMethod<"double", { value: number }, number>({
+  id: "double",
+});
+
+// Rejected at createSdk: this author wrote `double` for a display surface, so
+// it formats instead of computing. The declaration promised a number.
+defineMethod({
+  name: "double",
+  run: ({ input }: { input: { value: number } }) => `${input.value * 2}`,
+});
+
+// Also rejected: an `item` method is a fine plugin, but the declaration asked
+// for a bare number, not an envelope.
+defineMethod({
+  name: "double",
+  output: "item",
+  run: async ({ input }: { input: { value: number } }) => ({
+    data: input.value * 2,
+  }),
+});
+
+// Accepted.
+defineMethod({
+  name: "double",
+  run: ({ input }: { input: { value: number } }) => input.value * 2,
+});
+```
+
+Two modules declaring one id independently is the intended use, and stays legal while they agree. They are caught when they disagree, because no single provider can satisfy both. Every reachable provider under an id must honor the contract, so a sound `declareDefault` beside an unsound explicit provider is still rejected: the explicit one is what the runtime picks.
+
+An optional reference is checked the same way when a provider does appear. Its contract is the binding a consumer sees, so `undefined` is part of it: a consumer of an optional reference handles the absent case regardless, and a by-reference provider is allowed to pass `undefined` explicitly.
+
+A module reference (`declarePlugin`) is checked through its export references, leaf by leaf, so a module method typed differently from its reference is caught. What is NOT checked is whether the real module exports everything the reference promised: only the module's own id is a requirement, so a promised export the module lacks still fails at runtime.
+
+Spell the contract out. An id-only `declareMethod<"double">({ id: "double" })` defaults to `unknown` on both sides. That makes it over-strict on input, since a consumer may call it with no argument and any provider needing real input is rejected, and vacuous on output, since every provider returns a subtype of `unknown`. No `declare*` call opts out of the compatibility check.
+
+What the graph checks do NOT reach. A `defineHook` carries no summary, so a declaration reachable only through a hook's `imports` is checked by neither ledger. `addPlugin` performs no graph checks at all. And a positional surface cannot be declared by id: `declareMethod` describes an object call only, so a positional provider is correctly rejected against one, and referencing a positional method means casting past the ledger (`curl` does exactly that for `fetch`). Those three are limitations, not design.
+
+If you annotate a plugin by hand rather than letting `define*` infer it, pass the contract. `LeafSummary` takes the surfaced binding as a fourth argument (`LeafSummary<"", "setup", typeof imports, MethodContract<SetupOptions, Promise<void>>>`), and a reference is `DeclarationSummary<TId, TBinding>` or `OptionalDeclarationSummary<TId, TBinding>`. A `PluginSummary` written with two arguments still compiles and declares no contract, so a hand-annotated plugin drops out of the compatibility check silently.
+
 ## Defaults
 
 When you _own_ a capability slot and can ship a working implementation, register it as a default with `declareDefault({ plugin })` rather than referencing it. A default is a real, single node in the graph, so it works out of the box, hooks and middleware can wrap it, and an explicit provider of the same id silently preempts it (that is the seam for userland or another plugin to replace it).

package/dist/index.cjs

@@ -775,6 +775,11 @@ function toIterable(source) {
   return { [Symbol.asyncIterator]: () => source[Symbol.asyncIterator]() };
 }
 
+// src/utils/promise-utils.ts
+function isPromiseLike(value) {
+  return value !== null && typeof value === "object" && typeof value.then === "function";
+}
+
 // src/utils/validation.ts
 var parseOrThrow = (schema, input, { adaptError } = {}) => {
   const result = schema.safeParse(input);
@@ -1241,7 +1246,7 @@ function createRawFunction(coreFn, options) {
       try {
         const parsed = schema ? validateOptions(schema, input, { adaptError }) : input;
         const result = coreFn(parsed, context);
-        if (result !== null && typeof result === "object" && typeof result.then === "function") {
+        if (isPromiseLike(result)) {
           return result.then(
             (value) => {
               fireEnd();
@@ -2023,8 +2028,9 @@ function declareOptionalMethod(config) {
         `Plugin "${id}" is an optional stand-in (declareOptionalMethod) with no implementation. Its binding is \`undefined\` unless a real plugin is registered under this id.`
       );
     }
-    // Requires nothing (phantom carrier `<never, never>`): a consumer that
-    // imports it still passes `createSdk`'s completeness check unprovided. The
+    // Requires nothing: a consumer that imports it still passes `createSdk`'s
+    // completeness check unprovided. The contract is still carried, so a
+    // provider that DOES appear under the id is checked against it. The
     // `optional: true` literal drives `PluginSurface` to type the binding
     // `| undefined`.
   };
@@ -2074,9 +2080,12 @@ function declareOptionalProperty(config) {
     optional: true,
     imports: [],
     importBindings: []
-    // Requires nothing (phantom carrier `<never, never>`): a consumer that
-    // imports it still passes `createSdk`'s completeness check unprovided. The
-    // import binding is still typed `TValue | undefined` from the descriptor.
+    // Requires nothing: a consumer that imports it still passes `createSdk`'s
+    // completeness check unprovided. The contract is the binding a consumer
+    // sees, `TValue | undefined`, which is also what a by-reference provider
+    // (`defineProperty(ref, { value })`) is allowed to pass. A consumer of an
+    // optional reference has to handle the absent case either way, so an
+    // explicit `undefined` breaks nothing a narrower contract would protect.
   };
 }
 function declareDefault({
@@ -2573,9 +2582,6 @@ function applyListOutputPolicy(page, policy) {
 var FRAMEWORK_CONFIGURATION_IDS = /* @__PURE__ */ new Set([
   CORE_OPTIONS_ID
 ]);
-function isPromiseLike(value) {
-  return value !== null && typeof value === "object" && typeof value.then === "function";
-}
 function normalizeOutput(output) {
   if (output === void 0) return { type: "raw" };
   if (typeof output === "string") return { type: output };
@@ -5062,6 +5068,7 @@ var DEFAULT_IDEMPOTENT_METHODS = [
   "TRACE"
 ];
 var BASE_BACKOFF_MILLISECONDS = 1e3;
+var MIN_BACKOFF_MILLISECONDS = 100;
 var JITTER_FACTOR = 0.5;
 var EPOCH_THRESHOLD_SECONDS = 1e9;
 function directedDelayMilliseconds(response) {
@@ -5086,6 +5093,12 @@ function backoffMilliseconds(attemptNumber) {
   const base = BASE_BACKOFF_MILLISECONDS * 2 ** (attemptNumber - 1);
   return base + Math.random() * JITTER_FACTOR * base;
 }
+function clampBackoffMilliseconds(attemptNumber, maxDelayMilliseconds) {
+  return Math.max(
+    Math.min(backoffMilliseconds(attemptNumber), maxDelayMilliseconds),
+    MIN_BACKOFF_MILLISECONDS
+  );
+}
 function abortReason(signal) {
   const reason = signal?.reason;
   return reason ?? new Error("The request was aborted.");
@@ -5120,6 +5133,20 @@ var retryHttpRequestPlugin = defineHook({
       const maxDelayMilliseconds = options.maxDelayMilliseconds ?? DEFAULT_MAX_DELAY_MILLISECONDS;
       const idempotentMethods = options.idempotentMethods ?? DEFAULT_IDEMPOTENT_METHODS;
       const statuses = isIdempotent(input.request, idempotentMethods) ? options.retryStatuses ?? DEFAULT_RETRY_STATUSES : options.nonIdempotentRetryStatuses ?? DEFAULT_NON_IDEMPOTENT_RETRY_STATUSES;
+      const notifyRetry = (notice) => {
+        try {
+          const observed = options.onRetry?.({
+            ...notice,
+            request: input.attempt.operation.request,
+            operationId: input.attempt.operation.operationId
+          });
+          if (isPromiseLike(observed)) {
+            void observed.then(void 0, () => {
+            });
+          }
+        } catch {
+        }
+      };
       for (let attemptNumber = 1; ; attemptNumber++) {
         const attempt = {
           ...input.attempt,
@@ -5141,10 +5168,16 @@ var retryHttpRequestPlugin = defineHook({
           )) {
             throw error;
           }
-          await sleep(
-            Math.min(backoffMilliseconds(attemptNumber), maxDelayMilliseconds),
-            attempt.signal
+          const errorDelay = clampBackoffMilliseconds(
+            attemptNumber,
+            maxDelayMilliseconds
           );
+          notifyRetry({
+            attemptNumber,
+            delayMilliseconds: errorDelay,
+            error
+          });
+          await sleep(errorDelay, attempt.signal);
           continue;
         }
         if (!statuses.includes(response.status) || !canRetry(
@@ -5157,10 +5190,8 @@ var retryHttpRequestPlugin = defineHook({
         const directed = directedDelayMilliseconds(response);
         if (directed != null && directed > maxDelayMilliseconds)
           return response;
-        const delay = Math.min(
-          directed ?? backoffMilliseconds(attemptNumber),
-          maxDelayMilliseconds
-        );
+        const delay = directed ?? clampBackoffMilliseconds(attemptNumber, maxDelayMilliseconds);
+        notifyRetry({ attemptNumber, delayMilliseconds: delay, response });
         await response.body?.cancel().catch(() => {
         });
         await sleep(delay, attempt.signal);