Skip to content

upstash/workflow-js / skills

upstash-workflow-js

Unverified

Lightweight guidance for using the Upstash Workflow SDK to define, trigger, and manage workflows. Use this Skill whenever a user wants to create workflow endpoints, run steps, or interact with the Upstash Workflow client.

FileKindSize
SKILL.mdskill md2.2 KB
agents.mdmarkdown6.7 KB
basics/client.mdmarkdown4.1 KB
basics/context.mdmarkdown5.1 KB
basics/serve.mdmarkdown2.4 KB
features/flow-control.mdmarkdown3.9 KB
features/invoke.mdmarkdown2.6 KB
features/retries-failures-reliability.mdmarkdown6.3 KB
features/wait-for-event.mdmarkdown2.8 KB
features/webhooks.mdmarkdown2.5 KB
how-to/local-dev.mdmarkdown3.2 KB
how-to/middleware.mdmarkdown4.7 KB
how-to/migrations.mdmarkdown4.8 KB
how-to/realtime.mdmarkdown4.8 KB
rest-api.mdmarkdown6.6 KB
troubleshooting.mdmarkdown4.8 KB

basics/context.md

View on GitHub
# Workflow Context Basics

This skill documents all workflow context functions available inside a TypeScript workflow. It focuses on how these APIs behave, how their parameters interact, and common pitfalls when composing them into reliable long‑running workflows.

---

## context.api

`context.api` provides typed integrations for OpenAI, Anthropic, and Resend. These calls behave like `context.call` but enforce the correct operation names and body types.

### Key points

- Each provider exposes a `.call(stepName, config)` function.
- `token` is always required.
- The `operation` field selects the API method.
- `body` must match the provider's type definitions.
- Returns `{ status, body }`.

### Example (combined)

```ts
// OpenAI + Anthropic + Resend usage
const openai = await context.api.openai.call("openai chat", {
  token: process.env.OPENAI_API_KEY!,
  operation: "chat.completions.create",
  body: {
    model: "gpt-4o",
    messages: [
      { role: "system", content: "Hello" },
      { role: "user", content: "Hi" },
    ],
  },
});

const anthropic = await context.api.anthropic.call("anthropic message", {
  token: process.env.ANTHROPIC_API_KEY!,
  operation: "messages.create",
  body: {
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello" }],
  },
});

// Resend email
const email = await context.api.resend.call("send email", {
  token: process.env.RESEND_API_KEY!,
  headers: { "content-type": "application/json" },
  body: {
    from: "Acme <onboarding@resend.dev>",
    to: ["someone@example.com"],
    subject: "Welcome",
    html: "<p>Hi!</p>",
  },
});
```

---

## context.call

Performs an HTTP request with long execution windows (up to 12 hours). Always returns a response, even for non‑2xx status codes.

### Important parameters

- `url`: required.
- `method`: defaults to `GET`.
- `headers`: object.
- `body`: body as string.
- `retries`: number of retry attempts.
- `retryDelay`: retry delay expression as string or number (in milliseconds).
- `flowControl`: throttling config.
- `timeout`: seconds for each attempt.
- `workflow`: used only when invoking a workflow inside `serveMany`.

### Example (showing most fields)

```ts
const response = await context.call("sync user", {
  url: "https://api.example.com/user",
  method: "POST",
  headers: { authorization: `Bearer ${process.env.TOKEN}` },
  body: JSON.stringify({ id: userId, name }),
  retries: 3,
  retryDelay: "pow(2, retried)", // exponential
  timeout: 20,
  flowControl: {
    key: "user-sync",
    rate: 5,
    parallelism: 2,
  },
});
```

### Pitfalls

- Localhost requests fail unless tunneled.

---

## context.cancel

Cancels the current workflow run.

- Workflow is marked **canceled**, not failed.
- `failureFunction` does not run.
- No DLQ entry.

### Example

```ts
const result = await context.run("check something", () => ...);
if (result.cancel) await context.cancel();
```

---

## context.createWebhook

Creates a reusable webhook URL for external systems.

### Example

```ts
const { webhookUrl, eventId } = await context.createWebhook("create webhook");
// Use webhookUrl with an external service
```

---

## context.invoke

Invokes another workflow (must be served under the same `serveMany`) and waits for its completion.

### Key parameters

- `workflow`: the workflow definition.
- `body`: becomes `requestPayload` of invoked workflow.
- `headers`: forwarded headers.
- `workflowRunId`: optional override.
- `retries`, `retryDelay`, `flowControl`: control invocation retry strategy.

### Example

```ts
const { body, isFailed, isCanceled } = await context.invoke("invoke child", {
  workflow: childWorkflow,
  body: { id: 123 },
  headers: { foo: "bar" },
  retries: 2,
});
```

---

## context.notify

Notifies waiting workflows created via `context.waitForEvent`.

### Example

```ts
const { notifyResponse } = await context.notify("notify step", "order-updated", {
  status: "shipped",
});
```

`notifyResponse` lists all workflows resumed by this event.

---

## context.run

Runs custom synchronous or async logic as a step. Values must be JSON‑serializable.

### Example

```ts
const user = await context.run("load user", () => getUser());

await context.run("process user", () => process(user));

// Running in parallel
const a = context.run("step A", () => foo());
const b = context.run("step B", () => bar());
await Promise.all([a, b]);
```

### Pitfalls

- Returned class instances lose methods due to serialization. Rehydrate via `Object.assign(new Class(), data)`.

---

## context.sleep

Pauses workflow execution for a duration. String or numeric seconds.

### Example

```ts
await context.sleep("wait 1 day", "1d");
```

---

## context.sleepUntil

Pauses execution until a specific `Date`, timestamp, or parseable string.

### Example

```ts
const ts = new Date(Date.now() + 1000 * 60 * 60);
await context.sleepUntil("wait until", ts);
```

---

## context.waitForEvent

Waits for an event (triggered by `context.notify`) or until timeout.

### Example

```ts
const { eventData, timeout } = await context.waitForEvent("wait for update", "order-updated", {
  timeout: "2h",
});
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall