From cbce046b1555da107d5d0788791cbf2f04f50533 Mon Sep 17 00:00:00 2001
From: Duncan Mackenzie <duncan.mackenzie@temporal.io>
Date: Mon, 5 Oct 2026 11:57:46 -0700
Subject: [PATCH] Fix TypeScript samples that use APIs missing from @temporalio
 1.24.0

- fixed-count-retries: import RetryState from @temporalio/common; the
  workflow package doesn't re-export it.
- fixed-wall-time-retries: TimeoutFailure has timeoutType, not type; import
  TimeoutType from @temporalio/common.
- testing-suite: fix the heatbeat import typo.
- temporal-client: client.getHandle() was the old WorkflowClient API; use
  client.workflow.getHandle(). Drop the redundant second handle declaration
  in the start sample.
- workflow-streams: the TypeScript SDK has no executeActivity; call the
  Activity through proxyActivities.
---
 docs/design-patterns/fixed-count-retries.mdx           |  3 ++-
 docs/design-patterns/fixed-wall-time-retries.mdx       |  3 ++-
 .../typescript/best-practices/testing-suite.mdx        |  2 +-
 docs/develop/typescript/client/temporal-client.mdx     |  5 ++---
 docs/develop/typescript/workflows/workflow-streams.mdx | 10 ++++++----
 5 files changed, 13 insertions(+), 10 deletions(-)

diff --git a/docs/design-patterns/fixed-count-retries.mdx b/docs/design-patterns/fixed-count-retries.mdx
index 058c4a90ce..99140acba6 100644
--- a/docs/design-patterns/fixed-count-retries.mdx
+++ b/docs/design-patterns/fixed-count-retries.mdx
@@ -190,6 +190,7 @@ public class PaymentWorkflowImpl implements PaymentWorkflow {
 
 ```typescript
 // workflows.ts
+import { RetryState } from '@temporalio/common';
 import * as wf from '@temporalio/workflow';
 import type * as activities from './activities';
 
@@ -202,7 +203,7 @@ export async function paymentWorkflow(orderId: string): Promise<string> {
     try {
         return await chargePaymentApi(orderId);
     } catch (err) {
-        if (err instanceof wf.ActivityFailure && err.retryState === wf.RetryState.MAXIMUM_ATTEMPTS_REACHED) {
+        if (err instanceof wf.ActivityFailure && err.retryState === RetryState.MAXIMUM_ATTEMPTS_REACHED) {
             // All retries exhausted — handle the failure here.
             // Options: alert on-call, trigger a compensation activity, or escalate to a human.
             wf.log.error('Payment failed: all 3 attempts exhausted', { orderId });
diff --git a/docs/design-patterns/fixed-wall-time-retries.mdx b/docs/design-patterns/fixed-wall-time-retries.mdx
index 3166752a29..e6751dfaf4 100644
--- a/docs/design-patterns/fixed-wall-time-retries.mdx
+++ b/docs/design-patterns/fixed-wall-time-retries.mdx
@@ -200,6 +200,7 @@ public class PaymentAuthWorkflowImpl implements PaymentAuthWorkflow {
 
 ```typescript
 // workflows.ts
+import { TimeoutType } from '@temporalio/common';
 import * as wf from '@temporalio/workflow';
 import type * as activities from './activities';
 
@@ -219,7 +220,7 @@ export async function paymentAuthWorkflow(transactionId: string): Promise<string
     } catch (err) {
         if (err instanceof wf.ActivityFailure) {
             const cause = err.cause;
-            if (cause instanceof wf.TimeoutFailure && cause.type === wf.TimeoutType.SCHEDULE_TO_CLOSE) {
+            if (cause instanceof wf.TimeoutFailure && cause.timeoutType === TimeoutType.SCHEDULE_TO_CLOSE) {
                 wf.log.error('Authorization failed — 2-minute SLA breached', { transactionId });
             }
         }
diff --git a/docs/develop/typescript/best-practices/testing-suite.mdx b/docs/develop/typescript/best-practices/testing-suite.mdx
index f975a81b05..f79c5d57e3 100644
--- a/docs/develop/typescript/best-practices/testing-suite.mdx
+++ b/docs/develop/typescript/best-practices/testing-suite.mdx
@@ -107,7 +107,7 @@ If an Activity is supposed to react to a Cancellation, you can test whether it r
 [`MockActivityEnvironment`](https://typescript.temporal.io/api/classes/testing.MockActivityEnvironment) exposes a [`.cancel()`](https://typescript.temporal.io/api/classes/testing.MockActivityEnvironment#cancel) method that cancels the Activity Context.
 
 ```ts
-import { CancelledFailure, heatbeat, sleep } from '@temporalio/activity';
+import { CancelledFailure, heartbeat, sleep } from '@temporalio/activity';
 import { MockActivityEnvironment } from '@temporalio/testing';
 import assert from 'assert';
 
diff --git a/docs/develop/typescript/client/temporal-client.mdx b/docs/develop/typescript/client/temporal-client.mdx
index e9f996833d..addd65c804 100644
--- a/docs/develop/typescript/client/temporal-client.mdx
+++ b/docs/develop/typescript/client/temporal-client.mdx
@@ -664,7 +664,6 @@ const handle = await client.workflow.start(example, {
   taskQueue: 'your-task-queue',
   args: ['argument01', 'argument02', 'argument03'], // this is typechecked against workflowFn's args
 });
-const handle = client.getHandle(workflowId);
 const result = await handle.result();
 ```
 
@@ -811,7 +810,7 @@ If you started a Workflow with `client.workflow.start()`, you can choose to wait
 `handle.result()`.
 
 ```typescript
-const handle = client.getHandle(workflowId);
+const handle = client.workflow.getHandle(workflowId);
 const result = await handle.result();
 ```
 
@@ -822,7 +821,7 @@ If you call `result()` on a Workflow that prematurely ended for some reason, it
 reason. For that reason, it is recommended to catch that error.
 
 ```typescript
-const handle = client.getHandle(workflowId);
+const handle = client.workflow.getHandle(workflowId);
 try {
   const result = await handle.result();
 } catch (err) {
diff --git a/docs/develop/typescript/workflows/workflow-streams.mdx b/docs/develop/typescript/workflows/workflow-streams.mdx
index f2eced3e78..b9769bf534 100644
--- a/docs/develop/typescript/workflows/workflow-streams.mdx
+++ b/docs/develop/typescript/workflows/workflow-streams.mdx
@@ -411,10 +411,14 @@ export async function streamCompletion(prompt: string): Promise<string> {
 <TabItem value="workflow" label="workflows.ts">
 
 ```typescript
-import { condition, defineSignal, executeActivity, setHandler } from '@temporalio/workflow';
+import { condition, defineSignal, proxyActivities, setHandler } from '@temporalio/workflow';
 import { WorkflowStream } from '@temporalio/workflow-streams/workflow';
 import type * as activities from './activities';
 
+const { streamCompletion } = proxyActivities<typeof activities>({
+  startToCloseTimeout: '5 minutes',
+});
+
 export const subscriberAcknowledgedTerminator = defineSignal('subscriberAcknowledgedTerminator');
 
 export interface ChatInput {
@@ -428,9 +432,7 @@ export async function chatWorkflow(input: ChatInput): Promise<string> {
     subscriberDone = true;
   });
 
-  const result = await executeActivity<typeof activities.streamCompletion>('streamCompletion', input.prompt, {
-    startToCloseTimeout: '5 minutes',
-  });
+  const result = await streamCompletion(input.prompt);
 
   // Wait for the subscriber to ack the terminal `close` event. The timeout
   // is a fallback for when no subscriber is attached; with the ack, the