@keystrokehq/skills 0.0.1

package/keystroke-workflow-authoring/references/patterns.md

@@ -0,0 +1,265 @@
+# Workflow And Step / Operation Examples
+
+Use these examples when the user needs a concrete pattern instead of only rules.
+
+`Operation`, `Step`, and `Tool` are aliases for the same class. In this workflow reference, examples default to `Step` because that name reads best from workflow context.
+
+File layout reminder:
+
+- keep every exported primitive in its own typed file
+- `*.workflow.ts` exports one workflow
+- `*.step.ts`, `*.tool.ts`, or `*.operation.ts` exports one operation
+- if a snippet shows multiple primitives together, treat it as a multi-file excerpt and import the reused symbols from their own files
+
+## Minimal workflow
+
+```ts
+import { Workflow } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const helloWorkflow = new Workflow({
+  id: 'hello-workflow',
+  name: 'Hello Workflow',
+  description: 'Returns a greeting.',
+  input: z.object({
+    name: z.string(),
+  }),
+  output: z.object({
+    message: z.string(),
+  }),
+  run: async (input) => {
+    return {
+      message: `Hello, ${input.name}!`,
+    };
+  },
+});
+```
+
+In normal Keystroke usage, deploy the workflow and enter it through triggers, endpoints, or the UI. Direct `workflow.run(...)` calls are mainly for tests and local authoring.
+
+Author workflows as top-level exports like this. Do not hide workflow definitions inside factory functions.
+
+## Workflow with triggers
+
+```ts
+import { cronTrigger, webhookTrigger, Workflow } from '@keystrokehq/core';
+import { z } from 'zod';
+
+const PayloadSchema = z.object({ accountId: z.string() });
+
+const accountCron = cronTrigger({
+  name: 'Nightly Account Sync',
+  schedule: '0 0 * * *',
+  input: PayloadSchema,
+  payload: { accountId: 'default' },
+});
+
+const accountWebhook = webhookTrigger({
+  name: 'Account Webhook',
+  source: {
+    type: 'custom',
+    method: 'POST',
+    path: '/accounts',
+  },
+  payload: z.object({ id: z.string(), action: z.string() }),
+  filter: (p) => p.action === 'sync',
+});
+
+export const accountSyncWorkflow = new Workflow({
+  id: 'account-sync',
+  name: 'Account Sync',
+  input: PayloadSchema,
+  output: z.object({ ok: z.boolean() }),
+  triggers: [
+    accountCron,
+    accountWebhook({
+      transform: (payload) => ({ accountId: payload.id }),
+    }),
+  ],
+  run: async () => ({ ok: true }),
+});
+```
+
+Bare triggers (like `accountCron` above) pass their payload directly as workflow input. Call the trigger with `{ transform }` when the payload shape differs from the workflow input.
+
+## Workflow metadata fields
+
+```ts
+import { Workflow } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const versionedWorkflow = new Workflow({
+  id: 'billing-digest',
+  name: 'Billing Digest',
+  description: 'Builds a digest for the billing team.',
+  author: 'Keystroke Team',
+  version: '1.0.0',
+  tags: ['billing', 'digest'],
+  timeout: '15m',
+  retries: {
+    exponential: { attempts: 2, base: 2, multiplier: 2 },
+  },
+  input: z.object({
+    tenantId: z.string(),
+  }),
+  output: z.object({
+    ok: z.boolean(),
+  }),
+  run: async () => ({ ok: true }),
+});
+```
+
+## Step with retries and timeout
+
+```ts
+import { Step } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const fetchInvoice = new Step({
+  name: 'Fetch Invoice',
+  description: 'Loads the current invoice.',
+  input: z.object({
+    invoiceId: z.string(),
+  }),
+  output: z.object({
+    invoiceId: z.string(),
+    amount: z.number(),
+  }),
+  timeout: '2m',
+  retries: {
+    constant: { attempts: 3, seconds: 30 },
+  },
+  tags: ['billing'],
+  run: async (input) => {
+    return {
+      invoiceId: input.invoiceId,
+      amount: 100,
+    };
+  },
+});
+```
+
+This is the normal place for side effects such as API calls, database writes, or non-deterministic work.
+
+The same example could also be written with `new Operation({...})` if the unit is shared outside workflow code.
+
+## Step with workflow globals
+
+```ts
+import { Step, Workflow } from '@keystrokehq/core';
+import { z } from 'zod';
+
+const sendDigest = new Step({
+  name: 'Send Digest',
+  description: 'Uses workflow globals to decide where to send the digest.',
+  workflowGlobals: z.object({
+    defaultChannel: z.string(),
+  }),
+  input: z.object({
+    message: z.string(),
+  }),
+  output: z.object({
+    channel: z.string(),
+  }),
+  run: async (_input, ctx) => {
+    return {
+      channel: ctx.workflowGlobals.defaultChannel,
+    };
+  },
+});
+
+export const digestWorkflow = new Workflow({
+  id: 'digest',
+  name: 'Digest',
+  input: z.object({}),
+  output: z.object({
+    channel: z.string(),
+  }),
+  workflowGlobals: z.object({
+    defaultChannel: z.string(),
+  }),
+  run: async () => sendDigest.run({ message: 'hello' }),
+});
+```
+
+## Step with credentials
+
+```ts
+import { CredentialSet, Step } from '@keystrokehq/core';
+import { z } from 'zod';
+
+const crmCredentials = new CredentialSet({
+  id: 'crmApi',
+  name: 'CRM API',
+  auth: z.object({
+    apiKey: z.string(),
+  }),
+});
+
+export const loadCustomer = new Step({
+  name: 'Load Customer',
+  description: 'Uses a credential set from step context.',
+  credentialSets: [crmCredentials],
+  input: z.object({
+    customerId: z.string(),
+  }),
+  output: z.object({
+    customerId: z.string(),
+    usedKey: z.string(),
+  }),
+  run: async (input, ctx) => {
+    return {
+      customerId: input.customerId,
+      usedKey: ctx.credentials.crmApi.apiKey,
+    };
+  },
+});
+```
+
+## Parallel orchestration
+
+```ts
+const [a, b] = await Promise.all([
+  fetchInvoice.run({ invoiceId: 'inv_1' }),
+  fetchInvoice.run({ invoiceId: 'inv_2' }),
+]);
+```
+
+Use `Promise.all`, `Promise.race`, loops, and branches in the workflow. Keep network calls, database calls, and other side effects inside operations used as steps.
+
+## Child workflow composition
+
+```ts
+const prepareInvoice = new Workflow({
+  id: 'prepare-invoice',
+  name: 'Prepare Invoice',
+  input: z.object({ invoiceId: z.string() }),
+  output: z.object({ invoiceId: z.string() }),
+  run: async (input) => ({ invoiceId: input.invoiceId }),
+});
+
+const invoicePipeline = new Workflow({
+  id: 'invoice-pipeline',
+  name: 'Invoice Pipeline',
+  input: z.object({ invoiceId: z.string() }),
+  output: z.object({ invoiceId: z.string() }),
+  run: async (input) => {
+    return prepareInvoice.run(input);
+  },
+});
+```
+
+## `withTimeout(...)` and `retry(...)`
+
+```ts
+const fastHelloWorkflow = helloWorkflow.withTimeout('30s');
+const retriedHelloWorkflow = helloWorkflow.retry({
+  constant: { attempts: 2, seconds: 5 },
+});
+```
+
+## Replay-safe reminder
+
+- keep orchestration in `Workflow.run`
+- keep external effects in `Step.run` or `Operation.run`
+- keep random values and changing state out of the workflow body