zitejs 0.9.147 → 0.9.149

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/cjs/backend/index.d.ts +7 -1
  2. package/dist/cjs/bundle/index.d.ts +8 -0
  3. package/dist/cjs/bundle/index.js +9 -8
  4. package/dist/cjs/check/index.js +41 -25
  5. package/dist/cjs/client/index.d.ts +24 -0
  6. package/dist/cjs/integrations/rules.js +5 -3
  7. package/dist/cjs/runtime/index.d.ts +49 -19
  8. package/dist/cjs/runtime/sendEmailParamsTypes.test-d.d.ts +1 -0
  9. package/dist/cjs/runtime/sendEmailParamsTypes.test-d.js +32 -0
  10. package/dist/cjs/steps/index.d.ts +78 -0
  11. package/dist/cjs/steps/index.js +507 -0
  12. package/dist/cjs/steps/index.test.d.ts +1 -0
  13. package/dist/cjs/steps/index.test.js +635 -0
  14. package/dist/cjs/sync/lib.js +10 -6
  15. package/dist/cjs/sync/lib.test.js +100 -36
  16. package/dist/cjs/types/fields.d.ts +8 -1
  17. package/dist/cjs/types/fields.js +7 -1
  18. package/dist/cjs/types/tables.d.ts +16 -0
  19. package/dist/esm/backend/index.d.ts +7 -1
  20. package/dist/esm/bundle/index.d.ts +8 -0
  21. package/dist/esm/bundle/index.js +8 -8
  22. package/dist/esm/check/index.js +10 -27
  23. package/dist/esm/client/index.d.ts +24 -0
  24. package/dist/esm/integrations/rules.js +5 -3
  25. package/dist/esm/runtime/index.d.ts +49 -19
  26. package/dist/esm/runtime/sendEmailParamsTypes.test-d.d.ts +1 -0
  27. package/dist/esm/runtime/sendEmailParamsTypes.test-d.js +30 -0
  28. package/dist/esm/steps/index.d.ts +78 -0
  29. package/dist/esm/steps/index.js +502 -0
  30. package/dist/esm/steps/index.test.d.ts +1 -0
  31. package/dist/esm/steps/index.test.js +633 -0
  32. package/dist/esm/sync/lib.js +10 -6
  33. package/dist/esm/sync/lib.test.js +100 -36
  34. package/dist/esm/types/fields.d.ts +8 -1
  35. package/dist/esm/types/fields.js +6 -0
  36. package/dist/esm/types/tables.d.ts +16 -0
  37. package/package.json +9 -1
@@ -332,6 +332,11 @@ export interface ZiteStep {
332
332
  * In a run fired by a schedule, webhook or trigger, a step that throws is
333
333
  * tried again `retries` more times (default 3, at most 10), 30 seconds,
334
334
  * 2 minutes, then 10 minutes apart. Elsewhere its error fails the request.
335
+ * Once its tries are spent the code gets its error, and later calls of the
336
+ * run throw it there again, rebuilt as an `Error` with its `name`,
337
+ * `message` and plain fields such as `code` or `status`, so branch on
338
+ * those rather than on `instanceof`. A result over 256KB, or one JSON
339
+ * can't hold such as a cycle, fails the step without a retry.
335
340
  */
336
341
  run<T>(name: string, fn: () => Promise<T> | T, options?: ZiteStepOptions): Promise<T>;
337
342
  /**
@@ -342,7 +347,8 @@ export interface ZiteStep {
342
347
  *
343
348
  * The run continues in a later call, which runs `execute` again from the
344
349
  * top: finished steps return their saved results, and code outside a step
345
- * runs again, so keep side effects inside steps.
350
+ * runs again, so keep side effects inside steps. Call it between steps, not
351
+ * inside a step's code: a step can't pause halfway, so a sleep there throws.
346
352
  */
347
353
  sleep(name: string, duration: ZiteStepDuration): Promise<void>;
348
354
  /** Pause the run until `when`, at most 30 days ahead. See {@link ZiteStep.sleep}. */
@@ -20,10 +20,18 @@
20
20
  * "@babel/parser": "^7.26.0"
21
21
  */
22
22
  import * as esbuild from 'esbuild';
23
+ import { type SourceRoot } from '../sourceRoots.js';
23
24
  export declare const UNSUPPORTED_IN_WORKERD: Set<string>;
24
25
  export declare const BASE_BUILD_OPTIONS: esbuild.BuildOptions;
25
26
  export declare function createAliasPlugin(opts: {
26
27
  baseDir?: string;
27
28
  sdkPath?: string;
28
29
  }): esbuild.Plugin;
30
+ export interface EndpointBundleResult {
31
+ bundledEndpoints: Record<string, string>;
32
+ endpointErrors?: Record<string, string>;
33
+ bundledAuthHooks?: string;
34
+ authHooksError?: string;
35
+ }
36
+ export declare function bundleEndpoints(baseDir: string, root: SourceRoot, endpointNames: string[], logLevel: esbuild.LogLevel): Promise<EndpointBundleResult>;
29
37
  export declare function runBundle(): Promise<void>;
@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.BASE_BUILD_OPTIONS = exports.UNSUPPORTED_IN_WORKERD = void 0;
37
37
  exports.createAliasPlugin = createAliasPlugin;
38
+ exports.bundleEndpoints = bundleEndpoints;
38
39
  exports.runBundle = runBundle;
39
40
  /**
40
41
  * `npx zitejs bundle` — Bundle endpoint files for cloudflare-lambda deployment.
@@ -404,7 +405,7 @@ import endpoint from '${entryImport}';
404
405
  globalThis.__endpoint = endpoint;
405
406
  `;
406
407
  }
407
- async function bundleEndpointsImpl(baseDir, root, endpointNames) {
408
+ async function bundleEndpoints(baseDir, root, endpointNames, logLevel) {
408
409
  const bundledEndpoints = {};
409
410
  const endpointErrors = {};
410
411
  const aliasPlugin = createAliasPlugin({ baseDir });
@@ -441,7 +442,7 @@ async function bundleEndpointsImpl(baseDir, root, endpointNames) {
441
442
  resolveDir: `${baseDir}/src`,
442
443
  loader: 'ts',
443
444
  },
444
- logLevel: 'warning',
445
+ logLevel,
445
446
  plugins: [aliasPlugin],
446
447
  });
447
448
  if (result.warnings && result.warnings.length > 0) {
@@ -511,7 +512,7 @@ globalThis.__endpoint = endpoint;
511
512
  resolveDir: `${baseDir}/src`,
512
513
  loader: 'ts',
513
514
  },
514
- logLevel: 'warning',
515
+ logLevel,
515
516
  plugins: [aliasPlugin],
516
517
  });
517
518
  if (result.outputFiles && result.outputFiles.length > 0) {
@@ -538,14 +539,12 @@ globalThis.__endpoint = endpoint;
538
539
  }
539
540
  }
540
541
  }
541
- const output = JSON.stringify({
542
+ return {
542
543
  bundledEndpoints,
543
544
  endpointErrors: Object.keys(endpointErrors).length > 0 ? endpointErrors : undefined,
544
545
  bundledAuthHooks,
545
546
  authHooksError,
546
- });
547
- fs.writeFileSync('/tmp/zitejs-bundle-result.json', output);
548
- console.log(output);
547
+ };
549
548
  }
550
549
  async function bundleOneOffScriptImpl(scriptPath, sdkPath) {
551
550
  const rawScript = fs.readFileSync(scriptPath, 'utf-8');
@@ -663,5 +662,7 @@ async function runBundle() {
663
662
  endpointNames = (0, sourceRoots_js_1.listEndpointNames)(root, baseDir);
664
663
  }
665
664
  // Even with no endpoints, zite.auth.ts may still need bundling.
666
- return bundleEndpointsImpl(baseDir, root, endpointNames);
665
+ const output = JSON.stringify(await bundleEndpoints(baseDir, root, endpointNames, 'warning'));
666
+ fs.writeFileSync('/tmp/zitejs-bundle-result.json', output);
667
+ console.log(output);
667
668
  }
@@ -1,9 +1,44 @@
1
1
  "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
2
35
  Object.defineProperty(exports, "__esModule", { value: true });
3
36
  exports.runCheck = runCheck;
4
37
  const child_process_1 = require("child_process");
38
+ const esbuild = __importStar(require("esbuild"));
5
39
  const fs_1 = require("fs");
6
40
  const path_1 = require("path");
41
+ const index_js_1 = require("../bundle/index.js");
7
42
  const sourceRoots_js_1 = require("../sourceRoots.js");
8
43
  /**
9
44
  * An argument array, not a command string, so no shell is involved.
@@ -28,28 +63,9 @@ function run(file, args, cwd) {
28
63
  return { ok: false, output: (e.stderr ?? '') + (e.stdout ?? '') };
29
64
  }
30
65
  }
31
- /**
32
- * `zitejs bundle` reports per-endpoint failures inside its JSON payload and
33
- * still exits 0, so a non-empty `endpointErrors` is the only signal there is.
34
- */
35
- function bundleFailures(output) {
36
- const line = output
37
- .trim()
38
- .split('\n')
39
- .reverse()
40
- .find(l => l.startsWith('{'));
41
- if (!line)
42
- return ['bundle produced no result'];
43
- let result;
44
- try {
45
- result = JSON.parse(line);
46
- }
47
- catch {
48
- return [`could not parse bundle output: ${line.slice(0, 200)}`];
49
- }
66
+ async function bundleFailures(root, appPath, endpointNames) {
67
+ const result = await (0, index_js_1.bundleEndpoints)((0, path_1.resolve)(appPath), root, endpointNames, 'silent').finally(() => esbuild.stop());
50
68
  const failures = [];
51
- if (result.error)
52
- failures.push(result.error);
53
69
  for (const [name, err] of Object.entries(result.endpointErrors ?? {})) {
54
70
  failures.push(`${name}: ${err}`);
55
71
  }
@@ -65,7 +81,7 @@ async function runCheck() {
65
81
  process.exit(1);
66
82
  }
67
83
  let allPassed = true;
68
- for (const { root, dir: app, path: appPath } of appDirs) {
84
+ for (const { root, path: appPath } of appDirs) {
69
85
  console.log(`\n── ${appPath} ──`);
70
86
  // Only tsconfig.app.json compiles anything. The app's tsconfig.json is a
71
87
  // solution-style config — `"files": []` plus a reference — so
@@ -92,10 +108,10 @@ async function runCheck() {
92
108
  // Endpoints never reach vite — they are bundled separately for the lambda,
93
109
  // against a different resolver. tsc and vite both pass on an endpoint whose
94
110
  // `zitejs/*` alias has no generated file behind it; only the bundler knows.
95
- if ((0, sourceRoots_js_1.listEndpointNames)(root, appPath).length > 0) {
111
+ const endpointNames = (0, sourceRoots_js_1.listEndpointNames)(root, appPath);
112
+ if (endpointNames.length > 0) {
96
113
  process.stdout.write(' bundle endpoints ... ');
97
- const bundle = run('npx', ['zitejs', 'bundle', '--app', app], '.');
98
- const failures = bundle.ok ? bundleFailures(bundle.output) : [bundle.output];
114
+ const failures = await bundleFailures(root, appPath, endpointNames);
99
115
  if (failures.length === 0) {
100
116
  console.log('✓');
101
117
  }
@@ -275,6 +275,10 @@ export declare class Zite {
275
275
  sortEnabled?: boolean | undefined;
276
276
  resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
277
277
  };
278
+ } | {
279
+ name: string;
280
+ type: "created_by";
281
+ template: globalThis.Record<string, never>;
278
282
  } | {
279
283
  name: string;
280
284
  type: "updated_by";
@@ -488,6 +492,10 @@ export declare class Zite {
488
492
  sortEnabled?: boolean | undefined;
489
493
  resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
490
494
  };
495
+ } | {
496
+ name: string;
497
+ type: "created_by";
498
+ template: globalThis.Record<string, never>;
491
499
  } | {
492
500
  name: string;
493
501
  type: "updated_by";
@@ -711,6 +719,10 @@ export declare class Zite {
711
719
  sortEnabled?: boolean | undefined;
712
720
  resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
713
721
  };
722
+ } | {
723
+ name: string;
724
+ type: "created_by";
725
+ template: globalThis.Record<string, never>;
714
726
  } | {
715
727
  name: string;
716
728
  type: "updated_by";
@@ -937,6 +949,10 @@ export declare class Zite {
937
949
  sortEnabled?: boolean | undefined;
938
950
  resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
939
951
  };
952
+ } | {
953
+ name: string;
954
+ type: "created_by";
955
+ template: globalThis.Record<string, never>;
940
956
  } | {
941
957
  name: string;
942
958
  type: "updated_by";
@@ -1171,6 +1187,10 @@ export declare class Zite {
1171
1187
  sortEnabled?: boolean | undefined;
1172
1188
  resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
1173
1189
  };
1190
+ } | {
1191
+ name: string;
1192
+ type: "created_by";
1193
+ template: globalThis.Record<string, never>;
1174
1194
  } | {
1175
1195
  name: string;
1176
1196
  type: "updated_by";
@@ -1406,6 +1426,10 @@ export declare class Zite {
1406
1426
  sortEnabled?: boolean | undefined;
1407
1427
  resultType?: "number" | "boolean" | "date" | "array" | "text" | undefined;
1408
1428
  };
1429
+ } | {
1430
+ name: string;
1431
+ type: "created_by";
1432
+ template: globalThis.Record<string, never>;
1409
1433
  } | {
1410
1434
  name: string;
1411
1435
  type: "updated_by";
@@ -75,8 +75,8 @@ const FIELDS_BY_TYPE = {
75
75
  // one host to call.
76
76
  pipedrive: extras("apiBaseUrl"),
77
77
  // Shopify has no global API host: every call goes to the store's own domain
78
- // under a pinned API version. The storefront pair is the shopper-facing API,
79
- // which installs predating those scopes do not have.
78
+ // under a pinned API version. The storefront pair is the shopper-facing API;
79
+ // its URL comes from the store domain, so only the token can be missing.
80
80
  shopify: extras("shopDomain", "apiBaseUrl", "storefrontApiUrl", "storefrontAccessToken"),
81
81
  sharepoint: extras(),
82
82
  excel: extras(),
@@ -96,7 +96,9 @@ exports.OPTIONAL_CREDENTIAL_FIELDS = {
96
96
  // Only S3-compatible providers set an endpoint, and a prefix is opt-in.
97
97
  amazonS3: ["endpoint", "pathPrefix"],
98
98
  snowflake: ["warehouse"],
99
- shopify: ["storefrontApiUrl", "storefrontAccessToken"],
99
+ // A store that didn't grant the storefront scopes gets no token, and
100
+ // Shopify then serves the Storefront API tokenless.
101
+ shopify: ["storefrontAccessToken"],
100
102
  };
101
103
  /**
102
104
  * Types the runtime never serves: those with a generated client (Airtable, email,
@@ -85,20 +85,14 @@ export type FieldSelector<T> = Extract<keyof T, string> | (string & {});
85
85
  export interface TableFindAllOptions<T = Record<string, unknown>> {
86
86
  limit?: number;
87
87
  offset?: number;
88
- /**
89
- * IGNORED on the table path. `DatabasesFindAllParamsSchema` has no `sort`
90
- * key, so zod strips it before either dispatch, and neither destructures it.
91
- * Kept in the type because removing it would only turn a silent no-op into a
92
- * compile error for apps already passing it — the real fix is to forward it.
93
- * It DOES work on `zite.auth.findAllUsers`, which is dispatched separately.
94
- */
88
+ /** `[{ field, direction }]`, applied in order. */
95
89
  sort?: unknown[];
96
90
  filters?: RecordFilters<T>;
97
91
  /**
98
- * The nested filter format (`filters` is the legacy flat one). IGNORED here
99
- * for the same reason as `sort` — not in `DatabasesFindAllParamsSchema`, so
100
- * zod strips it — but kept so code already passing it still compiles. It IS
101
- * honored by `zite.auth.findAllUsers`.
92
+ * The nested filter format (`filters` is the legacy flat one). Ignored here:
93
+ * `DatabasesFindAllParamsSchema` has no `filter`, so zod strips it, but it's
94
+ * kept so code already passing it still compiles. `zite.auth.findAllUsers`
95
+ * honors it.
102
96
  */
103
97
  filter?: unknown;
104
98
  fields?: Array<FieldSelector<T>>;
@@ -272,6 +266,12 @@ export type EmailBlock = {
272
266
  label: string;
273
267
  href: string;
274
268
  alignment?: "left" | "center" | "right";
269
+ /** Hex colour, e.g. "#7c2d3a". Defaults to the platform blue. */
270
+ backgroundColor?: string;
271
+ /** Hex colour. Defaults to white. */
272
+ textColor?: string;
273
+ /** Corner radius in pixels. Defaults to 6. */
274
+ borderRadius?: number;
275
275
  } | {
276
276
  type: "image";
277
277
  src: string;
@@ -286,25 +286,23 @@ export type EmailBlock = {
286
286
  type: "divider";
287
287
  borderColor?: string;
288
288
  };
289
- export interface SendEmailParams {
289
+ interface SendEmailBaseParams {
290
290
  /** Recipient address(es). Must be valid emails — never placeholders like "me". */
291
291
  to: string | string[];
292
292
  subject: string;
293
- /** Email body as an array of content blocks. */
294
- body: EmailBlock[];
295
293
  cc?: string[];
296
294
  bcc?: string[];
297
295
  replyTo?: string;
298
- /** 'formatted' (default) for styled HTML, 'plain' for text-only. */
299
- layout?: "formatted" | "plain";
300
296
  /**
301
297
  * Text direction of the email. Use 'rtl' for right-to-left languages
302
298
  * (Hebrew, Arabic) — sets dir="rtl" on the email wrapper and right-aligns
303
- * text blocks. HTML like `<div dir="rtl">` inside text blocks is stripped
304
- * by the sanitizer and will NOT work. Defaults to 'ltr'.
299
+ * text. Defaults to 'ltr'.
305
300
  */
306
301
  direction?: "ltr" | "rtl";
307
- /** Custom logo shown above the email content (header area), for branding. */
302
+ /**
303
+ * Logo shown above the email content (header area), for branding. On an
304
+ * html email it replaces the brand kit's logo.
305
+ */
308
306
  logo?: {
309
307
  url: string;
310
308
  width?: number;
@@ -317,9 +315,41 @@ export interface SendEmailParams {
317
315
  contentType?: string;
318
316
  }[];
319
317
  }
318
+ /** An email written as HTML. */
319
+ export interface SendHtmlEmailParams extends SendEmailBaseParams {
320
+ /**
321
+ * Email-safe HTML: tables for layout, inline styles, `<a class="button">`
322
+ * for buttons. Sanitized and its `<style>` rules inlined at send time.
323
+ */
324
+ html: string;
325
+ /** Plain-text part. Generated from `html` when omitted. */
326
+ text?: string;
327
+ /**
328
+ * 'formatted' (default) puts the html in a card under the logo, in the
329
+ * app's brand kit; 'plain' drops the card and logo; 'none' sends the html
330
+ * as the whole document, with no frame or brand.
331
+ */
332
+ layout?: "formatted" | "plain" | "none";
333
+ body?: never;
334
+ }
335
+ /** An email written as an array of content blocks. */
336
+ export interface SendBlocksEmailParams extends SendEmailBaseParams {
337
+ /** Email body as an array of content blocks. */
338
+ body: EmailBlock[];
339
+ /**
340
+ * 'formatted' (default) for styled HTML, 'plain' for text-only. HTML like
341
+ * `<div dir="rtl">` inside text blocks is stripped by the sanitizer.
342
+ */
343
+ layout?: "formatted" | "plain";
344
+ html?: never;
345
+ text?: never;
346
+ }
347
+ export type SendEmailParams = SendHtmlEmailParams | SendBlocksEmailParams;
320
348
  export interface SendEmailResult {
321
349
  success: boolean;
322
350
  messageId: string;
351
+ /** Problems that did not stop the send, e.g. an email large enough for Gmail to clip. */
352
+ warnings?: string[];
323
353
  }
324
354
  export interface EmailClient {
325
355
  send(params: SendEmailParams): Promise<SendEmailResult>;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,32 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ const vitest_1 = require("vitest");
4
+ (0, vitest_1.test)("an email is written as html or as blocks, not both", () => {
5
+ (0, vitest_1.expectTypeOf)({
6
+ to: "a@example.com",
7
+ subject: "Hi",
8
+ html: "<p>Hi</p>",
9
+ layout: "none",
10
+ }).toExtend();
11
+ (0, vitest_1.expectTypeOf)({
12
+ to: "a@example.com",
13
+ subject: "Hi",
14
+ body: [{ type: "text", content: "Hi" }],
15
+ }).toExtend();
16
+ (0, vitest_1.expectTypeOf)({
17
+ to: "a@example.com",
18
+ subject: "Hi",
19
+ html: "<p>Hi</p>",
20
+ body: [],
21
+ }).not.toExtend();
22
+ (0, vitest_1.expectTypeOf)({
23
+ to: "a@example.com",
24
+ subject: "Hi",
25
+ body: [],
26
+ layout: "none",
27
+ }).not.toExtend();
28
+ (0, vitest_1.expectTypeOf)({
29
+ to: "a@example.com",
30
+ subject: "Hi",
31
+ }).not.toExtend();
32
+ });
@@ -0,0 +1,78 @@
1
+ import type { ZiteStep } from "../backend/index.js";
2
+ export declare const STEP_FAILURE_MEMO_KEY = "__ziteStepError";
3
+ export declare const STEP_FAILED_STEP_KEY = "__ziteFailedStep";
4
+ export declare const STEP_RESULT_MAX_BYTES: number;
5
+ export declare const STEP_SLEEP_MAX_MS: number;
6
+ export declare const STEP_DEFAULT_RETRIES = 3;
7
+ export declare const STEP_MAX_RETRIES = 10;
8
+ /** Why a durable call stops short. A retry outranks the other two. */
9
+ export type StepStop = {
10
+ kind: "retry";
11
+ name: string;
12
+ attempt: number;
13
+ error: unknown;
14
+ } | {
15
+ kind: "sleep";
16
+ name: string;
17
+ wakeAt: string;
18
+ } | {
19
+ kind: "step";
20
+ name: string;
21
+ };
22
+ /** A stop that isn't a failure: the run goes on at a wake time, or at once. */
23
+ export type StepSuspension = {
24
+ kind: "sleep";
25
+ name: string;
26
+ wakeAt: string;
27
+ } | {
28
+ kind: "step";
29
+ name: string;
30
+ };
31
+ /** A stop to try a step again: each failed step's next try, in the next call. */
32
+ export type StepRetry = {
33
+ step: string;
34
+ attempt: number;
35
+ attempts: Record<string, number>;
36
+ };
37
+ export type StepEventStatus = "ran" | "memoized" | "failed" | "sleeping" | "skipped";
38
+ export type StepRuntimeOptions = {
39
+ /** The run's saved steps by name, from earlier calls; filled in as steps save. */
40
+ memos: Record<string, unknown>;
41
+ /** A durable call may stop at a step for its orchestrator to call it again. */
42
+ durable: boolean;
43
+ /** Outside a durable call, what a sleep does: an editor test skips it, an app's request refuses it. */
44
+ sleeps?: "skip" | "refuse";
45
+ /** In a durable call, how long it starts new steps for. */
46
+ budgetMs?: number;
47
+ /**
48
+ * How long after the call starts `settle` waits for steps still working.
49
+ * A step past it runs again in the next call. Four minutes by default, so
50
+ * the call answers inside a five-minute request timeout.
51
+ */
52
+ deadlineMs?: number;
53
+ /** Which try each step that failed in an earlier call is on; others are on their first. */
54
+ attempts?: Record<string, number>;
55
+ /** Saves a step's result, or its final failure. Throws when it can't. */
56
+ save: (name: string, value: unknown, durationMs: number) => Promise<unknown>;
57
+ onEvent?: (name: string, status: StepEventStatus, durationMs?: number, extra?: Record<string, unknown>) => void;
58
+ /** Marks a failed save as the platform's failure rather than the app's. */
59
+ onPlatformFault?: (error: Error) => void;
60
+ now?: () => number;
61
+ };
62
+ export type StepRuntime = {
63
+ step: ZiteStep;
64
+ /** Resolves at the call's first stop. */
65
+ stopped: Promise<void>;
66
+ stop(): StepStop | undefined;
67
+ suspension(): StepSuspension | undefined;
68
+ retry(): StepRetry | undefined;
69
+ /** How many steps this call saved, sleeps included. */
70
+ saved(): number;
71
+ /**
72
+ * Waits for steps still doing work to save, including ones they start, but
73
+ * not for one stuck behind a stop, nor past the deadline.
74
+ */
75
+ settle(): Promise<void>;
76
+ };
77
+ export declare const isStepFailureMemo: (memo: unknown) => boolean;
78
+ export declare function createStepRuntime(options: StepRuntimeOptions): StepRuntime;