@zapier/kitcore 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @zapier/kitcore
 
+## 0.7.0
+
+### Minor Changes
+
+- 615fda9: The resolution controller now paginates dynamic selects as a page window: each `select` ask carries ONE page of choices plus a `page: { generation, index }` descriptor, so payloads stay proportional to a page.
+  - `next_page` and `previous_page` actions replace `more`.
+  - State carries coordinates only: `ControllerPagination` holds the cursor trail, never items, so the host carries cursors back between steps instead of the items it was just sent. An accumulating host appends pages client-side keyed on the question's `path` + `generation`, which increments whenever a `search` restarts the listing.
+  - Every question carries `path` (which field it is for), so hosts never read the state.
+  - Resolver `validate` is now a top-level callback (`validate({ imports, value, input, context })`), async and able to verify against the source; a thrown validate surfaces as a `failed` result with retry, not a rejection. A `validate` inside the prompt config is a type error (`ResolverPromptConfig` omits it), so it can't silently never run.
+  - The `exhausted` flag is removed; end-of-list is the absence of `next_page`.
+  - A failed fetch records its position so `retry` replays exactly the page that failed.
+
+- e6b22fb: `concatPaginated` now paginates with stateless cursors: each source is called with its own cursor per page (`({ cursor }) => ...`), outgoing cursors encode the source index plus that source's cursor, and a new `cursor` option resumes the stream from a previous page's cursor with no shared in-memory state. The `dedupe` option is removed; sources must be disjoint by construction.
+
+## 0.6.0
+
+### Minor Changes
+
+- 197a125: Breaking for plugin authors: an `output: "item"` method's `run` now returns the `{ data: item }` envelope itself (strictly `data`, no extra keys), symmetric with list's `SdkPage`, instead of returning the bare item for the framework to wrap. The public call surface is unchanged: callers still get `Promise<{ data: item }>`.
+
 ## 0.5.1
 
 ### Patch Changes

package/README.md

@@ -183,8 +183,13 @@ const transport = defineMethod({
   run: ({ input }) => fetch(input.url),
 });
 
-// item: run returns the value; the framework wraps it in { data }
-const getApp = defineMethod({ name: "getApp", output: "item", run: () => app });
+// item: run returns the { data } envelope itself (data and nothing else),
+// symmetric with list's page shape
+const getApp = defineMethod({
+  name: "getApp",
+  output: "item",
+  run: () => ({ data: app }),
+});
 const { data } = await sdk.getApp({ app: "slack" });
 
 // list: run returns one page; the surface is a paginated iterable

package/dist/index.cjs

@@ -301,7 +301,8 @@ function getCoreErrorCause(value) {
 var CURSOR_VERSION = 1;
 var CURSOR_SOURCE = {
   API: "api",
-  SDK: "sdk"
+  SDK: "sdk",
+  CONCAT: "concat"
 };
 function encodeBase64(str) {
   return btoa(
@@ -521,10 +522,32 @@ async function* paginateBuffered(pageFunction, pageOptions) {
   }
 }
 var paginate = paginateBuffered;
+function encodeConcatCursor(index, cursor) {
+  const envelope = {
+    v: CURSOR_VERSION,
+    source: CURSOR_SOURCE.CONCAT,
+    index,
+    cursor
+  };
+  return encodeBase64(JSON.stringify(envelope));
+}
+function decodeConcatCursor(incoming) {
+  if (!incoming) {
+    return { index: 0, cursor: void 0 };
+  }
+  try {
+    const envelope = JSON.parse(decodeBase64(incoming));
+    if (envelope.v === CURSOR_VERSION && envelope.source === CURSOR_SOURCE.CONCAT && typeof envelope.index === "number") {
+      return { index: envelope.index, cursor: envelope.cursor };
+    }
+  } catch {
+  }
+  return { index: 0, cursor: incoming };
+}
 function concatPaginated({
   sources,
-  dedupe,
-  pageSize = 100
+  pageSize = 100,
+  cursor
 }) {
   if (sources.length === 0) {
     const empty = { data: [] };
@@ -534,40 +557,24 @@ function concatPaginated({
       }
     });
   }
-  let sourceIndex = 0;
-  let currentIterator = null;
-  const seen = /* @__PURE__ */ new Set();
-  const pageFunction = async (_options) => {
-    while (sourceIndex < sources.length) {
-      if (!currentIterator) {
-        const result = sources[sourceIndex]();
-        currentIterator = result[Symbol.asyncIterator]();
-      }
-      const next = await currentIterator.next();
-      if (next.done) {
-        sourceIndex++;
-        currentIterator = null;
+  const pageFunction = async (options) => {
+    let { index, cursor: sourceCursor } = decodeConcatCursor(options.cursor);
+    while (index < sources.length) {
+      const page = await sources[index]({ cursor: sourceCursor });
+      const hasMoreInSource = page.nextCursor != null;
+      if (page.data.length === 0 && !hasMoreInSource) {
+        index++;
+        sourceCursor = void 0;
         continue;
       }
-      let items = next.value.data;
-      if (dedupe) {
-        if (sourceIndex > 0) {
-          items = items.filter((item) => !seen.has(dedupe(item)));
-        }
-        for (const item of items) {
-          seen.add(dedupe(item));
-        }
-      }
-      const hasMoreInSource = next.value.nextCursor != null;
-      const hasMoreSources = sourceIndex < sources.length - 1;
       return {
-        data: items,
-        nextCursor: hasMoreInSource || hasMoreSources ? "__has_more__" : void 0
+        data: page.data,
+        nextCursor: hasMoreInSource ? encodeConcatCursor(index, page.nextCursor) : index < sources.length - 1 ? encodeConcatCursor(index + 1, void 0) : void 0
       };
     }
     return { data: [] };
   };
-  const iterator = paginateBuffered(pageFunction, { pageSize });
+  const iterator = paginateBuffered(pageFunction, { pageSize, cursor });
   const firstPagePromise = iterator.next().then((result) => {
     if (result.done) {
       return { data: [] };
@@ -1448,6 +1455,7 @@ function defineResolver(config) {
         getContext: config.getContext,
         listItems: config.listItems,
         prompt: config.prompt,
+        validate: config.validate,
         tryResolveWithoutPrompt: config.tryResolveWithoutPrompt,
         tryResolveFromSearch: config.tryResolveFromSearch
       };
@@ -2106,6 +2114,7 @@ function bindResolver(resolver, plugins) {
       const {
         getContext: getContext2,
         listItems,
+        validate,
         tryResolveWithoutPrompt,
         tryResolveFromSearch
       } = resolver;
@@ -2119,6 +2128,9 @@ function bindResolver(resolver, plugins) {
       };
       if (getContext2)
         bound.getContext = ({ input }) => getContext2({ imports, input });
+      if (validate) {
+        bound.validate = ({ value, input, context }) => validate({ imports, value, input, context });
+      }
       if (tryResolveWithoutPrompt) {
         bound.tryResolveWithoutPrompt = ({ input }) => tryResolveWithoutPrompt({ imports, input });
       }
@@ -2274,9 +2286,7 @@ function buildMethodEntries(descriptors, context, states) {
         }
       );
     } else if (out.type === "item") {
-      const itemCore = async (input) => ({
-        data: await callRun(input)
-      });
+      const itemCore = async (input) => callRun(input);
       entry.value = createFunction(
         fold(itemCore),
         {
@@ -2800,14 +2810,14 @@ function coerce(leaf, raw) {
 }
 async function validationError(leaf, value, state) {
   if (leaf.resolver?.type !== "dynamic") return null;
+  const validate = leaf.resolver.validate;
+  if (!validate) return null;
   const context = await resolveContext(leaf, state.resolved);
-  const config = leaf.resolver.prompt?.({
-    items: state.listing?.items ?? [],
+  const verdict = await validate({
+    value,
     input: mergeInput(state.resolved, leaf.extraInput),
     context
   });
-  if (!config?.validate) return null;
-  const verdict = config.validate(value);
   if (verdict === true) return null;
   return typeof verdict === "string" ? verdict : `${leaf.name}: invalid value`;
 }
@@ -2933,20 +2943,36 @@ async function resolveContext(leaf, input) {
     input: mergeInput(input, leaf.extraInput)
   });
 }
-async function fetchListing(leaf, input, opts = {}) {
+function firstPagePosition(opts = {}) {
+  return {
+    ...opts.search !== void 0 ? { search: opts.search } : {},
+    pageCursor: null,
+    previousCursors: [],
+    generation: opts.generation ?? 0
+  };
+}
+async function fetchListing(leaf, input, position, context) {
+  if (leaf.resolver?.type === "dynamic" && leaf.resolver.inputType === "search" && position.search === void 0) {
+    return { position, items: [] };
+  }
   const page = await firstPage(
     leaf.resolver?.type === "dynamic" ? leaf.resolver.listItems({
       input: mergeInput(input, leaf.extraInput),
-      context: opts.context,
-      search: opts.search,
-      cursor: opts.cursor
+      context,
+      search: position.search,
+      cursor: position.pageCursor ?? void 0
     }) : void 0
   );
   return {
-    items: [...opts.priorItems ?? [], ...page.data],
-    cursor: page.nextCursor,
-    search: opts.search,
-    exhausted: page.nextCursor == null
+    position,
+    items: page.data,
+    ...page.nextCursor != null ? { nextCursor: page.nextCursor } : {}
+  };
+}
+function toPagination(page) {
+  return {
+    position: page.position,
+    ...page.nextCursor !== void 0 ? { nextCursor: page.nextCursor } : {}
   };
 }
 
@@ -2968,23 +2994,32 @@ var AFFORDANCE = {
     description: "Filter the options by a search term",
     supply: "term"
   },
-  more: { action: "more", description: "Load more options" },
+  nextPage: {
+    action: "next_page",
+    description: "Fetch the next page of options"
+  },
+  previousPage: {
+    action: "previous_page",
+    description: "Return to the previous page of options"
+  },
   skip: { action: "skip", description: "Omit this optional parameter" },
   add: { action: "add", description: "Add another item" },
   done: { action: "done", description: "Finish the list" },
   retry: { action: "retry", description: "Retry loading the options" },
   cancel: { action: "cancel", description: "Cancel resolution" }
 };
-function selectActions(leaf, listing, multiple) {
+function selectActions(leaf, page, multiple) {
   const searchMode = leaf.resolver?.type === "dynamic" && leaf.resolver.inputType === "search";
-  if (searchMode && listing.search === void 0 && listing.items.length === 0) {
+  if (searchMode && page.position.search === void 0 && page.items.length === 0) {
     const actions2 = multiple ? [AFFORDANCE.search] : [AFFORDANCE.search, AFFORDANCE.custom];
     if (!leaf.required) actions2.push(AFFORDANCE.skip);
     return actions2;
   }
   const actions = multiple ? [AFFORDANCE.choose] : [AFFORDANCE.choose, AFFORDANCE.custom];
   if (searchMode) actions.push(AFFORDANCE.search);
-  if (listing.cursor) actions.push(AFFORDANCE.more);
+  if (page.nextCursor) actions.push(AFFORDANCE.nextPage);
+  if (page.position.previousCursors.length > 0)
+    actions.push(AFFORDANCE.previousPage);
   if (!leaf.required) actions.push(AFFORDANCE.skip);
   return actions;
 }
@@ -2992,16 +3027,17 @@ function labeledMessage(leaf) {
   if (!leaf.label) return void 0;
   return `${leaf.label} (${leaf.required ? "required" : "optional"}):`;
 }
-function selectQuestion(leaf, input, listing, context) {
+function selectQuestion(leaf, path, input, page, context) {
   const resolver = leaf.resolver?.type === "dynamic" ? leaf.resolver : void 0;
   const config = resolver?.prompt?.({
-    items: listing.items,
+    items: page.items,
     input: mergeInput(input, leaf.extraInput),
     context
   });
   const multiple = config?.type === "checkbox";
   return {
     type: "select",
+    path,
     // A labeled field's title beats the resolver's message: per-field
     // resolvers are shared across fields (one choices-fetcher for every
     // field), so only the leaf knows which field is being asked.
@@ -3009,9 +3045,13 @@ function selectQuestion(leaf, input, listing, context) {
     choices: (config?.choices ?? []).map(toChoice),
     ...multiple ? { multiple: true } : {},
     ...config?.notes?.length ? { notes: config.notes } : {},
-    ...listing.search !== void 0 ? { search: listing.search } : {},
+    ...page.position.search !== void 0 ? { search: page.position.search } : {},
     ...resolver?.placeholder ? { placeholder: resolver.placeholder } : {},
-    actions: selectActions(leaf, listing, multiple)
+    page: {
+      generation: page.position.generation,
+      index: page.position.previousCursors.length
+    },
+    actions: selectActions(leaf, page, multiple)
   };
 }
 function toControllerError(error) {
@@ -3033,6 +3073,7 @@ function failedResult(state, name, error) {
       error: toControllerError(error),
       question: {
         type: "select",
+        path: state.current ?? [],
         message: `Could not load options for ${name}.`,
         choices: [],
         actions: [AFFORDANCE.retry, AFFORDANCE.cancel]
@@ -3040,27 +3081,15 @@ function failedResult(state, name, error) {
     }
   };
 }
-async function buildQuestion(leaf, input) {
+async function buildQuestion(leaf, path, input) {
   const optional = !leaf.required;
   const resolver = leaf.resolver;
   if (resolver?.type === "dynamic") {
     const context = await resolveContext(leaf, input);
-    if (resolver.inputType === "search") {
-      const listing2 = {
-        items: [],
-        cursor: void 0,
-        search: void 0,
-        exhausted: true
-      };
-      return {
-        question: selectQuestion(leaf, input, listing2, context),
-        listing: listing2
-      };
-    }
-    const listing = await fetchListing(leaf, input, { context });
+    const page = await fetchListing(leaf, input, firstPagePosition(), context);
     return {
-      question: selectQuestion(leaf, input, listing, context),
-      listing
+      question: selectQuestion(leaf, path, input, page, context),
+      pagination: toPagination(page)
     };
   }
   if (leaf.staticChoices) {
@@ -3069,6 +3098,7 @@ async function buildQuestion(leaf, input) {
     return {
       question: {
         type: "select",
+        path,
         message: `Select ${leaf.name}:`,
         choices: leaf.staticChoices,
         actions: actions2
@@ -3082,6 +3112,7 @@ async function buildQuestion(leaf, input) {
   return {
     question: {
       type: "input",
+      path,
       // The optional marker makes Enter-to-pass discoverable on a bare
       // parameter; a labeled field carries its marker via labeledMessage.
       message: labeledMessage(leaf) ?? `Enter ${leaf.name}${optional ? " (optional)" : ""}:`,
@@ -3096,6 +3127,7 @@ function collectionQuestion(t) {
   if (t.count >= t.min) actions.push(AFFORDANCE.done);
   return {
     type: "collection",
+    path: t.path,
     message: `Add ${t.path[t.path.length - 1]}[${t.count}]?`,
     container: "array",
     count: t.count,
@@ -3109,6 +3141,7 @@ function collectionQuestion(t) {
 function objectGateQuestion(path) {
   return {
     type: "collection",
+    path,
     message: `Add ${path[path.length - 1]}?`,
     container: "object",
     actions: [
@@ -3120,9 +3153,10 @@ function objectGateQuestion(path) {
     ]
   };
 }
-function optionalsGateQuestion(pending) {
+function optionalsGateQuestion(path, pending) {
   return {
     type: "collection",
+    path,
     // The prompt and its context ride separately so a host renders the info
     // line above the confirm without composing any text of its own.
     message: "Would you like to configure optional fields?",
@@ -3272,8 +3306,12 @@ async function askLeaf(state, path, leaf, opts = {}) {
   state.current = path;
   delete state.gate;
   try {
-    const { question, listing } = await buildQuestion(leaf, state.resolved);
-    state.listing = listing;
+    const { question, pagination } = await buildQuestion(
+      leaf,
+      path,
+      state.resolved
+    );
+    state.pagination = pagination;
     return {
       state,
       result: {
@@ -3283,7 +3321,7 @@ async function askLeaf(state, path, leaf, opts = {}) {
       }
     };
   } catch (error) {
-    state.listing = { items: [], exhausted: false };
+    state.pagination = failedPagination(void 0, firstPagePosition());
     return failedResult(state, leaf.name, error);
   }
 }
@@ -3293,13 +3331,13 @@ async function advance(ctx, state) {
     if (!target) {
       delete state.current;
       delete state.gate;
-      delete state.listing;
+      delete state.pagination;
       return { state, result: finalize(ctx, state.resolved) };
     }
     if (target.kind === "array") {
       state.current = target.path;
       state.gate = "array";
-      delete state.listing;
+      delete state.pagination;
       return {
         state,
         result: { status: "ask", question: collectionQuestion(target) }
@@ -3308,7 +3346,7 @@ async function advance(ctx, state) {
     if (target.kind === "object") {
       state.current = target.path;
       state.gate = "entry";
-      delete state.listing;
+      delete state.pagination;
       return {
         state,
         result: { status: "ask", question: objectGateQuestion(target.path) }
@@ -3317,12 +3355,12 @@ async function advance(ctx, state) {
     if (target.kind === "optionals") {
       state.current = target.path;
       state.gate = "optionals";
-      delete state.listing;
+      delete state.pagination;
       return {
         state,
         result: {
           status: "ask",
-          question: optionalsGateQuestion(target.pending)
+          question: optionalsGateQuestion(target.path, target.pending)
         }
       };
     }
@@ -3373,13 +3411,13 @@ async function step(ctx, prior, action) {
   if (action.type === "cancel") {
     delete state.current;
     delete state.gate;
-    delete state.listing;
+    delete state.pagination;
     return { state, result: { status: "cancelled" } };
   }
   const path = state.current;
   if (!path) throw new Error("step called with no outstanding question");
   const leaf = await leafAt(ctx, path, state.resolved);
-  if (leaf && (action.type === "search" || action.type === "more" || action.type === "retry")) {
+  if (leaf && (action.type === "search" || action.type === "next_page" || action.type === "previous_page" || action.type === "retry")) {
     return refine(ctx, state, leaf, path, action);
   }
   if (action.type === "add" || action.type === "done") {
@@ -3391,7 +3429,7 @@ async function step(ctx, prior, action) {
     }
     delete state.current;
     delete state.gate;
-    delete state.listing;
+    delete state.pagination;
     if (action.type === "done") {
       settle(state, path);
       return advance(ctx, state);
@@ -3420,23 +3458,44 @@ async function step(ctx, prior, action) {
     case "choose":
     case "custom": {
       if (leaf) {
-        const error = await validationError(leaf, action.value, state);
+        let error;
+        try {
+          error = await validationError(leaf, action.value, state);
+        } catch (thrown) {
+          return failedResult(state, leaf.name, thrown);
+        }
         if (error) {
-          if (state.listing && leaf.resolver?.type === "dynamic") {
-            const context = await resolveContext(leaf, state.resolved);
-            return {
-              state,
-              result: {
-                status: "ask",
-                question: selectQuestion(
-                  leaf,
-                  state.resolved,
-                  state.listing,
-                  context
-                ),
-                error
-              }
-            };
+          if (state.pagination && leaf.resolver?.type === "dynamic") {
+            try {
+              const context = await resolveContext(leaf, state.resolved);
+              const page = await fetchListing(
+                leaf,
+                state.resolved,
+                state.pagination.position,
+                context
+              );
+              state.pagination = toPagination(page);
+              return {
+                state,
+                result: {
+                  status: "ask",
+                  question: selectQuestion(
+                    leaf,
+                    path,
+                    state.resolved,
+                    page,
+                    context
+                  ),
+                  error
+                }
+              };
+            } catch (fetchError) {
+              state.pagination = failedPagination(
+                state.pagination,
+                state.pagination.position
+              );
+              return failedResult(state, leaf.name, fetchError);
+            }
           }
           return askLeaf(state, path, leaf, { error });
         }
@@ -3455,15 +3514,11 @@ async function step(ctx, prior, action) {
       throw new Error(`action "${action.type}" is not supported here`);
   }
   delete state.current;
-  delete state.listing;
+  delete state.pagination;
   return advance(ctx, state);
 }
 async function refine(ctx, state, leaf, path, action) {
-  const attempt = action.type === "search" ? { search: action.term, cursor: void 0, priorItems: [] } : {
-    search: state.listing?.search,
-    cursor: state.listing?.cursor,
-    priorItems: state.listing?.items ?? []
-  };
+  const position = positionAfter(state.pagination, action);
   try {
     if (action.type === "search") {
       const exact = leaf.resolver?.type === "dynamic" ? await leaf.resolver.tryResolveFromSearch?.({
@@ -3473,32 +3528,62 @@ async function refine(ctx, state, leaf, path, action) {
       if (exact) {
         setAtPath(state.resolved, path, coerce(leaf, exact.resolvedValue));
         delete state.current;
-        delete state.listing;
+        delete state.pagination;
         return advance(ctx, state);
       }
     }
     const context = await resolveContext(leaf, state.resolved);
-    state.listing = await fetchListing(leaf, state.resolved, {
-      ...attempt,
-      context
-    });
+    const page = await fetchListing(leaf, state.resolved, position, context);
+    state.pagination = toPagination(page);
     return {
       state,
       result: {
         status: "ask",
-        question: selectQuestion(leaf, state.resolved, state.listing, context)
+        question: selectQuestion(leaf, path, state.resolved, page, context)
       }
     };
   } catch (error) {
-    state.listing = {
-      items: attempt.priorItems,
-      search: attempt.search,
-      cursor: attempt.cursor,
-      exhausted: false
-    };
+    state.pagination = failedPagination(state.pagination, position);
     return failedResult(state, leaf.name, error);
   }
 }
+function failedPagination(pagination, retryPosition) {
+  return {
+    position: pagination?.position ?? firstPagePosition(),
+    ...pagination?.nextCursor !== void 0 ? { nextCursor: pagination.nextCursor } : {},
+    retryPosition
+  };
+}
+function positionAfter(pagination, action) {
+  const current = pagination?.position ?? firstPagePosition();
+  switch (action.type) {
+    case "search":
+      return firstPagePosition({
+        search: action.term,
+        generation: current.generation + 1
+      });
+    case "next_page": {
+      if (pagination?.nextCursor == null) return current;
+      return {
+        ...current.search !== void 0 ? { search: current.search } : {},
+        pageCursor: pagination.nextCursor,
+        previousCursors: [...current.previousCursors, current.pageCursor],
+        generation: current.generation
+      };
+    }
+    case "previous_page": {
+      if (current.previousCursors.length === 0) return current;
+      return {
+        ...current.search !== void 0 ? { search: current.search } : {},
+        pageCursor: current.previousCursors[current.previousCursors.length - 1],
+        previousCursors: current.previousCursors.slice(0, -1),
+        generation: current.generation
+      };
+    }
+    case "retry":
+      return pagination?.retryPosition ?? current;
+  }
+}
 
 // src/model/resolution/controller.ts
 function toJsonSchema(schema) {