add idempotency docs (vercel#19)

* add idempotency docs

* Update docs/content/docs/foundations/errors-and-retries.mdx

Co-authored-by: Nathan Rajlich <n@n8.io>

* Update docs/content/docs/foundations/errors-and-retries.mdx

Co-authored-by: Nathan Rajlich <n@n8.io>

* Update docs/content/docs/foundations/idempotency.mdx

Co-authored-by: Nathan Rajlich <n@n8.io>

* Apply suggestion from @TooTallNate

---------

Co-authored-by: Nathan Rajlich <n@n8.io>

Author: ethanniser

docs/content/docs/api-reference/workflow/get-step-metadata.mdx

@@ -2,55 +2,83 @@
 title: getStepMetadata
 ---
 
-import { generateDefinition } from "@/lib/tsdoc"
+import { generateDefinition } from "@/lib/tsdoc";
 
 # `getStepMetadata`
 
 Returns metadata available in the current step function.
 
 You may want to use this function when you need to:
 
-* Track retry attempts in error handling
-* Access timing information of a step and execution metadata
+- Track retry attempts in error handling
+- Access timing information of a step and execution metadata
+- Generate idempotency keys for external APIs
 
 <Callout type="warn">
-This function can only be called inside a step function.
+  This function can only be called inside a step function.
 </Callout>
 
 ```typescript lineNumbers
-import { getStepMetadata } from "workflow"
+import { getStepMetadata } from "workflow";
 
 async function testWorkflow() {
-    "use workflow"
-    await logStepId()
+  "use workflow";
+  await logStepId();
 }
 
 async function logStepId() {
-    "use step"
-    const ctx = getStepMetadata() // [!code highlight]
-    console.log(ctx.stepId) // Grab the current step ID
+  "use step";
+  const ctx = getStepMetadata(); // [!code highlight]
+  console.log(ctx.stepId); // Grab the current step ID
 }
 ```
 
+### Example: Use `stepId` as an idempotency key
+
+```typescript lineNumbers
+import { getStepMetadata } from "workflow";
+
+async function chargeUser(userId: string, amount: number) {
+  "use step";
+  const { stepId } = getStepMetadata();
+
+  await stripe.charges.create(
+    {
+      amount,
+      currency: "usd",
+      customer: userId,
+    },
+    {
+      idempotencyKey: `charge:${stepId}`, // [!code highlight]
+    }
+  );
+}
+```
+
+<Callout type="info">
+  Learn more about patterns and caveats in the{" "}
+  <a href="/docs/foundations/idempotency">Idempotency</a> guide.
+</Callout>
+
 ## API Signature
 
 ### Parameters
 
 <TSDoc
-definition={generateDefinition({
-  code: `
+  definition={generateDefinition({
+    code: `
 import { getStepMetadata } from "workflow";
-export default getStepMetadata;`
-})}
-showSections={['parameters']}
+export default getStepMetadata;`,
+  })}
+  showSections={["parameters"]}
 />
 
 ### Returns
 
 <TSDoc
-definition={generateDefinition({
-  code: `
+  definition={generateDefinition({
+    code: `
 import type { StepMetadata } from "workflow";
-export default StepMetadata;`
-})}
+export default StepMetadata;`,
+  })}
 />

docs/content/docs/foundations/errors-and-retries.mdx

@@ -31,12 +31,19 @@ callApi.maxRetries = 5; // Set a custom number of retries
 
 Steps get enqueued immediately after the failure. Read on to see how this can be customized.
 
+<Callout type="info">
+  When a retried step performs external side effects (payments, emails, API
+  writes), ensure those calls are <strong>idempotent</strong> to avoid duplicate
+  side effects. See <a href="/docs/foundations/idempotency">Idempotency</a> for
+  more information.
+</Callout>
+
 ## Intentional Errors
 
 When your step needs to intentionally throw an error and skip retrying, simply throw a [`FatalError`](/docs/api-reference/workflow/fatal-error).
 
 ```typescript lineNumbers
-import { FatalError } from 'workflow';
+import { FatalError } from "workflow";
 
 async function callApi(endpoint: string) {
   "use step";
@@ -61,7 +68,7 @@ async function callApi(endpoint: string) {
 When you need to customize the delay on the retry, use [`RetryableError`](/docs/api-reference/workflow/retryable-error)and set the retryAfter property.
 
 ```typescript lineNumbers
-import { FatalError, RetryableError } from 'workflow';
+import { FatalError, RetryableError } from "workflow";
 
 async function callApi(endpoint: string) {
   "use step";
@@ -77,10 +84,10 @@ async function callApi(endpoint: string) {
   }
 
   if (response.status === 429) {
-    const retryAfter = response.headers.get('Retry-After');
+    const retryAfter = response.headers.get("Retry-After");
     // Delay the retry until after a timeout
     throw new RetryableError("Too many requests. Retrying...", { // [!code highlight]
-      retryAfter: parseInt(retryAfter) // [!code highlight]
+      retryAfter: parseInt(retryAfter), // [!code highlight]
     }); // [!code highlight]
   }
 
@@ -93,7 +100,7 @@ async function callApi(endpoint: string) {
 This final example combines everything we've learnt, along with [`getStepMetadata`](/docs/api-reference/workflow/get-step-metadata).
 
 ```typescript lineNumbers
-import { FatalError, RetryableError, getStepMetadata } from 'workflow';
+import { FatalError, RetryableError, getStepMetadata } from "workflow";
 
 async function callApi(endpoint: string) {
   "use step";
@@ -104,18 +111,20 @@ async function callApi(endpoint: string) {
 
   if (response.status >= 500) {
     // Exponential backoffs
-    throw new RetryableError("Backing off...", { retryAfter: metadata.attempt ** 2 }); // [!code highlight]
+    throw new RetryableError("Backing off...", {
+      retryAfter: metadata.attempt ** 2,  // [!code highlight]
+    });
   }
 
   if (response.status === 404) {
     throw new FatalError("Resource not found. Skipping retries.");
   }
 
   if (response.status === 429) {
-    const retryAfter = response.headers.get('Retry-After');
+    const retryAfter = response.headers.get("Retry-After");
     // Delay the retry until after a timeout
     throw new RetryableError("Too many requests. Retrying...", {
-      retryAfter: parseInt(retryAfter)
+      retryAfter: parseInt(retryAfter),
     });
   }
 

docs/content/docs/foundations/idempotency.mdx

@@ -0,0 +1,63 @@
+---
+title: Idempotency
+---
+
+# Idempotency
+
+Idempotency is a property of an operation that ensures it can be safely retried without producing duplicate side effects.
+
+In distributed systems (calling external APIs), it is not always possible to ensure an operation has only been performed once just by seeing if it succeeds.
+Consider a payment API that charges the user $10, but due to network failures, the confirmation response is lost. When the step retries (because the previous attempt was considered a failure), it will charge the user again.
+
+To prevent this, many external APIs support idempotency keys. An idempotency key is a unique identifier for an operation that can be used to deduplicate requests.
+
+---
+
+## The core pattern: use the step ID as your idempotency key
+
+Every step invocation has a stable `stepId` that stays the same across retries.
+Use it as the idempotency key when calling third-party APIs.
+
+```typescript lineNumbers
+import { getStepMetadata } from "workflow";
+
+async function chargeUser(userId: string, amount: number) {
+  "use step";
+
+  const { stepId } = getStepMetadata();
+
+  // Example: Stripe-style idempotency key
+  // This guarantees only one charge is created even if the step retries
+  await stripe.charges.create(
+    {
+      amount,
+      currency: "usd",
+      customer: userId,
+    },
+    {
+      idempotencyKey: stepId, // [!code highlight]
+    }
+  );
+}
+```
+
+Why this works:
+
+- **Stable across retries**: `stepId` does not change between attempts.
+- **Globally unique per step**: Fulfills the uniqueness requirement for an idempotency key.
+
+---
+
+## Best practices
+
+- **Always provide idempotency keys to external side effects that are not idempotent** inside steps (payments, emails, SMS, queues).
+- **Prefer `stepId` as your key**; it is stable across retries and unique per step.
+- **Keep keys deterministic**; avoid including timestamps or attempt counters.
+- **Handle 409/conflict responses** gracefully; treat them as success if the prior attempt completed.
+
+---
+
+## Related docs
+
+- Learn about retries in [Errors & Retrying](/docs/foundations/errors-and-retries)
+- API reference: [`getStepMetadata`](/docs/api-reference/workflow/get-step-metadata)

docs/content/docs/foundations/meta.json

@@ -4,6 +4,7 @@
     "workflows-and-steps",
     "control-flow-patterns",
     "errors-and-retries",
+    "idempotency",
     "hooks",
     "serialization"
   ],