@temporal-contract/worker 0.2.0 → 1.0.0

package/README.md

@@ -14,7 +14,7 @@ pnpm add @temporal-contract/worker @temporal-contract/contract @temporalio/workf
 
 ```typescript
 // activities.ts
-import { declareActivitiesHandler, ActivityError } from "@temporal-contract/worker/activity";
+import { declareActivitiesHandler, ApplicationFailure } from "@temporal-contract/worker/activity";
 import { Future, Result } from "@swan-io/boxed";
 
 export const activities = declareActivitiesHandler({
@@ -22,13 +22,12 @@ export const activities = declareActivitiesHandler({
   activities: {
     sendEmail: ({ to, body }) => {
       return Future.fromPromise(emailService.send({ to, body }))
-        .mapError(
-          (error) =>
-            new ActivityError(
-              "EMAIL_FAILED",
-              error instanceof Error ? error.message : "Failed to send email",
-              error,
-            ),
+        .mapError((error) =>
+          ApplicationFailure.create({
+            type: "EMAIL_FAILED",
+            message: error instanceof Error ? error.message : "Failed to send email",
+            cause: error,
+          }),
         )
         .mapOk(() => ({ sent: true }));
     },

package/dist/activity.cjs

@@ -1,103 +1,13 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_errors = require('./errors-DjSZg-93.cjs');
-
-//#region src/activity-utils.ts
-/**
-* Extract activity definitions for a specific workflow from a contract
-*
-* This includes both:
-* - Workflow-specific activities defined under workflow.activities
-* - Global activities defined under contract.activities
-*
-* @param contract - The contract definition
-* @param workflowName - The name of the workflow
-* @returns Activity definitions for the workflow (workflow-specific + global activities merged)
-*
-* @example
-* ```ts
-* const orderWorkflowActivities = getWorkflowActivities(myContract, 'processOrder');
-* // Returns: { processPayment: ActivityDef, reserveInventory: ActivityDef, sendEmail: ActivityDef }
-* // where sendEmail is a global activity
-* ```
-*/
-function getWorkflowActivities(contract, workflowName) {
-	const workflowActivities = contract.workflows[workflowName]?.activities || {};
-	return {
-		...contract.activities || {},
-		...workflowActivities
-	};
-}
-/**
-* Extract all activity names for a specific workflow from a contract
-*
-* @param contract - The contract definition
-* @param workflowName - The name of the workflow
-* @returns Array of activity names (strings) available for the workflow
-*
-* @example
-* ```ts
-* const activityNames = getWorkflowActivityNames(myContract, 'processOrder');
-* // Returns: ['processPayment', 'reserveInventory', 'sendEmail']
-* ```
-*/
-function getWorkflowActivityNames(contract, workflowName) {
-	const activities = getWorkflowActivities(contract, workflowName);
-	return Object.keys(activities);
-}
-/**
-* Check if an activity belongs to a specific workflow
-*
-* @param contract - The contract definition
-* @param workflowName - The name of the workflow
-* @param activityName - The name of the activity to check
-* @returns True if the activity is available for the workflow, false otherwise
-*
-* @example
-* ```ts
-* if (isWorkflowActivity(myContract, 'processOrder', 'processPayment')) {
-*   // Activity is available for this workflow
-* }
-* ```
-*/
-function isWorkflowActivity(contract, workflowName, activityName) {
-	return activityName in getWorkflowActivities(contract, workflowName);
-}
-/**
-* Get all workflow names from a contract
-*
-* @param contract - The contract definition
-* @returns Array of workflow names defined in the contract
-*
-* @example
-* ```ts
-* const workflows = getWorkflowNames(myContract);
-* // Returns: ['processOrder', 'processRefund']
-* ```
-*/
-function getWorkflowNames(contract) {
-	return Object.keys(contract.workflows);
-}
-
-//#endregion
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_internal = require("./internal-Tj4m4f_K.cjs");
+let _temporalio_common = require("@temporalio/common");
 //#region src/activity.ts
 /**
-* Activity error class that should be used to wrap all technical exceptions
-* Forces proper error handling and enables retry policies
-*/
-var ActivityError = class ActivityError extends Error {
-	constructor(code, message, cause) {
-		super(message, { cause });
-		this.code = code;
-		this.name = "ActivityError";
-		if (Error.captureStackTrace) Error.captureStackTrace(this, ActivityError);
-	}
-};
-/**
-* Create a typed activities handler with automatic validation and Result pattern
+* Create a typed activities handler with automatic validation and Result pattern.
 *
 * This wraps all activity implementations with:
 * - Validation at network boundaries
-* - Result<T, ActivityError> pattern for explicit error handling
+* - `Result<T, ApplicationFailure>` pattern for explicit error handling
 * - Automatic conversion from Result to Promise (throwing on Error)
 *
 * TypeScript ensures ALL activities (global + workflow-specific) are implemented.
@@ -106,28 +16,30 @@ var ActivityError = class ActivityError extends Error {
 *
 * @example
 * ```ts
-* import { declareActivitiesHandler, ActivityError } from '@temporal-contract/worker/activity';
+* import { declareActivitiesHandler, ApplicationFailure } from '@temporal-contract/worker/activity';
 * import { Result, Future } from '@swan-io/boxed';
 * import myContract from './contract';
 *
 * export const activities = declareActivitiesHandler({
 *   contract: myContract,
 *   activities: {
-*     // Activity returns Result instead of throwing
-*     // All technical exceptions must be wrapped in ActivityError for retry policies
+*     // Activity returns Result instead of throwing.
 *     sendEmail: (args) => {
-*       return Future.make(async resolve => {
+*       return Future.make(async (resolve) => {
 *         try {
 *           await emailService.send(args);
 *           resolve(Result.Ok({ sent: true }));
 *         } catch (error) {
-*           // Wrap technical errors in ActivityError to enable retries
+*           // Wrap technical errors in ApplicationFailure. `nonRetryable`
+*           // is per-instance: set it to true on permanent failures so
+*           // Temporal stops retrying immediately.
 *           resolve(Result.Error(
-*             new ActivityError(
-*               'EMAIL_SEND_FAILED',
-*               'Failed to send email',
-*               error // Original error as cause for debugging
-*             )
+*             ApplicationFailure.create({
+*               type: 'EMAIL_SEND_FAILED',
+*               message: 'Failed to send email',
+*               nonRetryable: false,
+*               cause: error instanceof Error ? error : undefined,
+*             }),
 *           ));
 *         }
 *       });
@@ -144,19 +56,32 @@ var ActivityError = class ActivityError extends Error {
 *   taskQueue: contract.taskQueue,
 * });
 * ```
+*
+* @remarks
+* The wrapper accepts implementations in the
+* `Future<Result<T, ApplicationFailure>>` shape and produces ordinary
+* Promise-returning Temporal handlers (Result.Error → thrown
+* `ApplicationFailure`; Result.Ok → output validated against the
+* contract and resolved). It does **not** hide Temporal's
+* `@temporalio/activity` runtime: inside the body you can still call
+* `Context.current()` from `@temporalio/activity` to access heartbeats
+* (`heartbeat(details)`, `heartbeatDetails`), activity info (attempt
+* number, workflow IDs), and the async-completion task token. See the
+* "Working with the Activity Context" section of the worker
+* implementation guide for end-to-end examples.
 */
 function declareActivitiesHandler(options) {
 	const { contract, activities } = options;
 	const wrappedActivities = {};
 	function makeWrapped(activityName, activityDef, activityImpl) {
 		return async (...args) => {
-			const input = args.length === 1 ? args[0] : args;
+			const input = require_internal.extractHandlerInput(args);
 			const inputResult = await activityDef.input["~standard"].validate(input);
-			if (inputResult.issues) throw new require_errors.ActivityInputValidationError(activityName, inputResult.issues);
+			if (inputResult.issues) throw new require_internal.ActivityInputValidationError(activityName, inputResult.issues);
 			const result = await activityImpl(inputResult.value);
 			if (result.isOk()) {
 				const outputResult = await activityDef.output["~standard"].validate(result.value);
-				if (outputResult.issues) throw new require_errors.ActivityOutputValidationError(activityName, outputResult.issues);
+				if (outputResult.issues) throw new require_internal.ActivityOutputValidationError(activityName, outputResult.issues);
 				return outputResult.value;
 			} else throw result.error;
 		};
@@ -164,7 +89,7 @@ function declareActivitiesHandler(options) {
 	if (contract.activities) for (const [activityName, impl] of Object.entries(activities)) {
 		if (contract.workflows && activityName in contract.workflows) continue;
 		const activityDef = contract.activities[activityName];
-		if (!activityDef) throw new require_errors.ActivityDefinitionNotFoundError(activityName, Object.keys(contract.activities));
+		if (!activityDef) throw new require_internal.ActivityDefinitionNotFoundError(activityName, Object.keys(contract.activities));
 		wrappedActivities[activityName] = makeWrapped(activityName, activityDef, impl);
 	}
 	if (contract.workflows) for (const [workflowName, workflowDef] of Object.entries(contract.workflows)) {
@@ -173,20 +98,20 @@ function declareActivitiesHandler(options) {
 		const wfDefs = workflowDef.activities ?? {};
 		for (const [activityName, impl] of Object.entries(wfActivitiesImpl)) {
 			const activityDef = wfDefs[activityName];
-			if (!activityDef) throw new require_errors.ActivityDefinitionNotFoundError(`${workflowName}.${activityName}`, Object.keys(wfDefs));
+			if (!activityDef) throw new require_internal.ActivityDefinitionNotFoundError(`${workflowName}.${activityName}`, Object.keys(wfDefs));
 			wrappedActivities[activityName] = makeWrapped(`${workflowName}.${activityName}`, activityDef, impl);
 		}
 	}
 	return wrappedActivities;
 }
-
 //#endregion
-exports.ActivityDefinitionNotFoundError = require_errors.ActivityDefinitionNotFoundError;
-exports.ActivityError = ActivityError;
-exports.ActivityInputValidationError = require_errors.ActivityInputValidationError;
-exports.ActivityOutputValidationError = require_errors.ActivityOutputValidationError;
+exports.ActivityDefinitionNotFoundError = require_internal.ActivityDefinitionNotFoundError;
+exports.ActivityInputValidationError = require_internal.ActivityInputValidationError;
+exports.ActivityOutputValidationError = require_internal.ActivityOutputValidationError;
+Object.defineProperty(exports, "ApplicationFailure", {
+	enumerable: true,
+	get: function() {
+		return _temporalio_common.ApplicationFailure;
+	}
+});
 exports.declareActivitiesHandler = declareActivitiesHandler;
-exports.getWorkflowActivities = getWorkflowActivities;
-exports.getWorkflowActivityNames = getWorkflowActivityNames;
-exports.getWorkflowNames = getWorkflowNames;
-exports.isWorkflowActivity = isWorkflowActivity;

package/dist/activity.d.cts

@@ -1,24 +1,19 @@
-import { g as WorkerInferOutput, h as WorkerInferInput, n as ActivityInputValidationError, r as ActivityOutputValidationError, t as ActivityDefinitionNotFoundError } from "./errors-4jH78z8m.cjs";
-import { i as isWorkflowActivity, n as getWorkflowActivityNames, r as getWorkflowNames, t as getWorkflowActivities } from "./activity-utils-RsXOceIH.cjs";
+import { _ as WorkerInferOutput, g as WorkerInferInput, n as ActivityInputValidationError, r as ActivityOutputValidationError, t as ActivityDefinitionNotFoundError } from "./errors-CG1y7SHO.cjs";
 import { ActivityDefinition, ContractDefinition } from "@temporal-contract/contract";
 import { Future, Result } from "@swan-io/boxed";
+import { ApplicationFailure, ApplicationFailure as ApplicationFailure$1 } from "@temporalio/common";
 
 //#region src/activity.d.ts
 /**
- * Activity error class that should be used to wrap all technical exceptions
- * Forces proper error handling and enables retry policies
- */
-declare class ActivityError extends Error {
-  readonly code: string;
-  constructor(code: string, message: string, cause?: unknown);
-}
-/**
- * Activity implementation using Future/Result pattern
+ * Activity implementation using Future/Result pattern.
  *
- * Returns Future<Result<Output, ActivityError>> for explicit error handling instead of throwing exceptions.
- * All errors must be wrapped in ActivityError to enable proper retry policies.
+ * Returns `Future<Result<Output, ApplicationFailure>>` for explicit error
+ * handling instead of throwing. The wrapper rethrows `Result.Error`
+ * payloads at the activity boundary; Temporal recognizes
+ * `ApplicationFailure` natively and applies the configured retry policy
+ * (with `nonRetryable: true` opting an instance out per-call).
  */
-type BoxedActivityImplementation<TActivity extends ActivityDefinition> = (args: WorkerInferInput<TActivity>) => Future<Result<WorkerInferOutput<TActivity>, ActivityError>>;
+type BoxedActivityImplementation<TActivity extends ActivityDefinition> = (args: WorkerInferInput<TActivity>) => Future<Result<WorkerInferOutput<TActivity>, ApplicationFailure$1>>;
 /**
  * Map of all activity implementations for a contract (global + all workflow-specific)
  */
@@ -41,11 +36,11 @@ type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) exten
  */
 type ActivitiesHandler<TContract extends ContractDefinition> = (TContract["activities"] extends Record<string, ActivityDefinition> ? ActivitiesImplementations<TContract["activities"]> : {}) & UnionToIntersection<{ [TWorkflow in keyof TContract["workflows"]]: TContract["workflows"][TWorkflow]["activities"] extends Record<string, ActivityDefinition> ? ActivitiesImplementations<TContract["workflows"][TWorkflow]["activities"]> : {} }[keyof TContract["workflows"]]>;
 /**
- * Create a typed activities handler with automatic validation and Result pattern
+ * Create a typed activities handler with automatic validation and Result pattern.
  *
  * This wraps all activity implementations with:
  * - Validation at network boundaries
- * - Result<T, ActivityError> pattern for explicit error handling
+ * - `Result<T, ApplicationFailure>` pattern for explicit error handling
  * - Automatic conversion from Result to Promise (throwing on Error)
  *
  * TypeScript ensures ALL activities (global + workflow-specific) are implemented.
@@ -54,28 +49,30 @@ type ActivitiesHandler<TContract extends ContractDefinition> = (TContract["activ
  *
  * @example
  * ```ts
- * import { declareActivitiesHandler, ActivityError } from '@temporal-contract/worker/activity';
+ * import { declareActivitiesHandler, ApplicationFailure } from '@temporal-contract/worker/activity';
  * import { Result, Future } from '@swan-io/boxed';
  * import myContract from './contract';
  *
  * export const activities = declareActivitiesHandler({
  *   contract: myContract,
  *   activities: {
- *     // Activity returns Result instead of throwing
- *     // All technical exceptions must be wrapped in ActivityError for retry policies
+ *     // Activity returns Result instead of throwing.
  *     sendEmail: (args) => {
- *       return Future.make(async resolve => {
+ *       return Future.make(async (resolve) => {
  *         try {
  *           await emailService.send(args);
  *           resolve(Result.Ok({ sent: true }));
  *         } catch (error) {
- *           // Wrap technical errors in ActivityError to enable retries
+ *           // Wrap technical errors in ApplicationFailure. `nonRetryable`
+ *           // is per-instance: set it to true on permanent failures so
+ *           // Temporal stops retrying immediately.
  *           resolve(Result.Error(
- *             new ActivityError(
- *               'EMAIL_SEND_FAILED',
- *               'Failed to send email',
- *               error // Original error as cause for debugging
- *             )
+ *             ApplicationFailure.create({
+ *               type: 'EMAIL_SEND_FAILED',
+ *               message: 'Failed to send email',
+ *               nonRetryable: false,
+ *               cause: error instanceof Error ? error : undefined,
+ *             }),
  *           ));
  *         }
  *       });
@@ -92,8 +89,21 @@ type ActivitiesHandler<TContract extends ContractDefinition> = (TContract["activ
  *   taskQueue: contract.taskQueue,
  * });
  * ```
+ *
+ * @remarks
+ * The wrapper accepts implementations in the
+ * `Future<Result<T, ApplicationFailure>>` shape and produces ordinary
+ * Promise-returning Temporal handlers (Result.Error → thrown
+ * `ApplicationFailure`; Result.Ok → output validated against the
+ * contract and resolved). It does **not** hide Temporal's
+ * `@temporalio/activity` runtime: inside the body you can still call
+ * `Context.current()` from `@temporalio/activity` to access heartbeats
+ * (`heartbeat(details)`, `heartbeatDetails`), activity info (attempt
+ * number, workflow IDs), and the async-completion task token. See the
+ * "Working with the Activity Context" section of the worker
+ * implementation guide for end-to-end examples.
  */
 declare function declareActivitiesHandler<TContract extends ContractDefinition>(options: DeclareActivitiesHandlerOptions<TContract>): ActivitiesHandler<TContract>;
 //#endregion
-export { ActivitiesHandler, ActivityDefinitionNotFoundError, ActivityError, ActivityInputValidationError, ActivityOutputValidationError, declareActivitiesHandler, getWorkflowActivities, getWorkflowActivityNames, getWorkflowNames, isWorkflowActivity };
+export { ActivitiesHandler, ActivityDefinitionNotFoundError, ActivityInputValidationError, ActivityOutputValidationError, ApplicationFailure, declareActivitiesHandler };
 //# sourceMappingURL=activity.d.cts.map

package/dist/activity.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"activity.d.cts","names":[],"sources":["../src/activity.ts"],"mappings":";;;;;;;AA2BA;;;cAAa,aAAA,SAAsB,KAAA;EAAA,SAEf,IAAA;cAAA,IAAA,UAChB,OAAA,UACA,KAAA;AAAA;;;;;;AASH;KAQI,2BAAA,mBAA8C,kBAAA,KACjD,IAAA,EAAM,gBAAA,CAAiB,SAAA,MACpB,MAAA,CAAO,MAAA,CAAO,iBAAA,CAAkB,SAAA,GAAY,aAAA;;;;KAK5C,sCAAA,mBAAyD,kBAAA,KAE3D,SAAA,uBAAgC,MAAA,SAAe,kBAAA,IAC5C,8BAAA,CAA+B,SAAA,8CAIX,SAAA,gBAAyB,SAAA,cAAuB,SAAA,wBAAiC,MAAA,SAEnG,kBAAA,IAEE,8BAAA,CAA+B,SAAA,cAAuB,SAAA;AAAA,KAI3D,8BAAA,qBAAmD,MAAA,SAAe,kBAAA,mBACzD,WAAA,GAAc,2BAAA,CAA4B,WAAA,CAAY,CAAA;;;;KAM/D,+BAAA,mBAAkD,kBAAA;EACrD,QAAA,EAAU,SAAA;EACV,UAAA,EAAY,sCAAA,CAAuC,SAAA;AAAA;AAAA,KAGhD,sBAAA,mBAAyC,kBAAA,KAC5C,IAAA,EAAM,gBAAA,CAAiB,SAAA,MACpB,OAAA,CAAQ,iBAAA,CAAkB,SAAA;AAAA,KAE1B,yBAAA,qBAA8C,MAAA,SAAe,kBAAA,mBACpD,WAAA,GAAc,sBAAA,CAAuB,WAAA,CAAY,CAAA;AAAA,KAG1D,mBAAA,OAA0B,CAAA,oBAAqB,CAAA,EAAG,CAAA,6BACrD,CAAA,sBAEE,CAAA;;;AA3C0D;;;KAmDlD,iBAAA,mBAAoC,kBAAA,KAE7C,SAAA,uBAAgC,MAAA,SAAe,kBAAA,IAC5C,yBAAA,CAA0B,SAAA,wBAG5B,mBAAA,uBAEwB,SAAA,gBAAyB,SAAA,cAAuB,SAAA,wBAAiC,MAAA,SAEnG,kBAAA,IAEE,yBAAA,CAA0B,SAAA,cAAuB,SAAA,8BAE/C,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAjD2D;;;;;;;;;;;;;;;;;;;;;AAKJ;iBAoGrD,wBAAA,mBAA2C,kBAAA,CAAA,CACzD,OAAA,EAAS,+BAAA,CAAgC,SAAA,IACxC,iBAAA,CAAkB,SAAA"}
+{"version":3,"file":"activity.d.cts","names":[],"sources":["../src/activity.ts"],"mappings":";;;;;;AAgCwD;;;;;;;;;AAAA,KAWnD,2BAAA,mBAA8C,kBAAA,KACjD,IAAA,EAAM,gBAAA,CAAiB,SAAA,MACpB,MAAA,CAAO,MAAA,CAAO,iBAAA,CAAkB,SAAA,GAAY,oBAAA;;;;KAK5C,sCAAA,mBAAyD,kBAAA,KAE3D,SAAA,uBAAgC,MAAA,SAAe,kBAAA,IAC5C,8BAAA,CAA+B,SAAA,8CAIX,SAAA,gBAAyB,SAAA,cAAuB,SAAA,wBAAiC,MAAA,SAEnG,kBAAA,IAEE,8BAAA,CAA+B,SAAA,cAAuB,SAAA;AAAA,KAI3D,8BAAA,qBAAmD,MAAA,SAAe,kBAAA,mBACzD,WAAA,GAAc,2BAAA,CAA4B,WAAA,CAAY,CAAA;;;;KAM/D,+BAAA,mBAAkD,kBAAA;EACrD,QAAA,EAAU,SAAA;EACV,UAAA,EAAY,sCAAA,CAAuC,SAAA;AAAA;AAAA,KAGhD,sBAAA,mBAAyC,kBAAA,KAC5C,IAAA,EAAM,gBAAA,CAAiB,SAAA,MACpB,OAAA,CAAQ,iBAAA,CAAkB,SAAA;AAAA,KAE1B,yBAAA,qBAA8C,MAAA,SAAe,kBAAA,mBACpD,WAAA,GAAc,sBAAA,CAAuB,WAAA,CAAY,CAAA;AAAA,KAG1D,mBAAA,OAA0B,CAAA,oBAAqB,CAAA,EAAG,CAAA,6BACrD,CAAA,sBAEE,CAAA;;;;;;KAQQ,iBAAA,mBAAoC,kBAAA,KAE7C,SAAA,uBAAgC,MAAA,SAAe,kBAAA,IAC5C,yBAAA,CAA0B,SAAA,wBAG5B,mBAAA,uBAEwB,SAAA,gBAAyB,SAAA,cAAuB,SAAA,wBAAiC,MAAA,SAEnG,kBAAA,IAEE,yBAAA,CAA0B,SAAA,cAAuB,SAAA,8BAE/C,SAAA;;;;;;;;;;;;;;;;;;;;;;;;AAjD2D;;;;;;;;;;;;;;;;;;;;;AAKJ;;;;;;;;;;;;;;;;;;AAQP;;;;;;iBA2G9C,wBAAA,mBAA2C,kBAAA,CAAA,CACzD,OAAA,EAAS,+BAAA,CAAgC,SAAA,IACxC,iBAAA,CAAkB,SAAA"}

package/dist/activity.d.mts

@@ -1,24 +1,19 @@
-import { g as WorkerInferOutput, h as WorkerInferInput, n as ActivityInputValidationError, r as ActivityOutputValidationError, t as ActivityDefinitionNotFoundError } from "./errors-CmTXZ3JW.mjs";
-import { i as isWorkflowActivity, n as getWorkflowActivityNames, r as getWorkflowNames, t as getWorkflowActivities } from "./activity-utils-B3vP03_P.mjs";
+import { _ as WorkerInferOutput, g as WorkerInferInput, n as ActivityInputValidationError, r as ActivityOutputValidationError, t as ActivityDefinitionNotFoundError } from "./errors-DZhaNhwr.mjs";
+import { ApplicationFailure, ApplicationFailure as ApplicationFailure$1 } from "@temporalio/common";
 import { ActivityDefinition, ContractDefinition } from "@temporal-contract/contract";
 import { Future, Result } from "@swan-io/boxed";
 
 //#region src/activity.d.ts
 /**
- * Activity error class that should be used to wrap all technical exceptions
- * Forces proper error handling and enables retry policies
- */
-declare class ActivityError extends Error {
-  readonly code: string;
-  constructor(code: string, message: string, cause?: unknown);
-}
-/**
- * Activity implementation using Future/Result pattern
+ * Activity implementation using Future/Result pattern.
  *
- * Returns Future<Result<Output, ActivityError>> for explicit error handling instead of throwing exceptions.
- * All errors must be wrapped in ActivityError to enable proper retry policies.
+ * Returns `Future<Result<Output, ApplicationFailure>>` for explicit error
+ * handling instead of throwing. The wrapper rethrows `Result.Error`
+ * payloads at the activity boundary; Temporal recognizes
+ * `ApplicationFailure` natively and applies the configured retry policy
+ * (with `nonRetryable: true` opting an instance out per-call).
  */
-type BoxedActivityImplementation<TActivity extends ActivityDefinition> = (args: WorkerInferInput<TActivity>) => Future<Result<WorkerInferOutput<TActivity>, ActivityError>>;
+type BoxedActivityImplementation<TActivity extends ActivityDefinition> = (args: WorkerInferInput<TActivity>) => Future<Result<WorkerInferOutput<TActivity>, ApplicationFailure$1>>;
 /**
  * Map of all activity implementations for a contract (global + all workflow-specific)
  */
@@ -41,11 +36,11 @@ type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) exten
  */
 type ActivitiesHandler<TContract extends ContractDefinition> = (TContract["activities"] extends Record<string, ActivityDefinition> ? ActivitiesImplementations<TContract["activities"]> : {}) & UnionToIntersection<{ [TWorkflow in keyof TContract["workflows"]]: TContract["workflows"][TWorkflow]["activities"] extends Record<string, ActivityDefinition> ? ActivitiesImplementations<TContract["workflows"][TWorkflow]["activities"]> : {} }[keyof TContract["workflows"]]>;
 /**
- * Create a typed activities handler with automatic validation and Result pattern
+ * Create a typed activities handler with automatic validation and Result pattern.
  *
  * This wraps all activity implementations with:
  * - Validation at network boundaries
- * - Result<T, ActivityError> pattern for explicit error handling
+ * - `Result<T, ApplicationFailure>` pattern for explicit error handling
  * - Automatic conversion from Result to Promise (throwing on Error)
  *
  * TypeScript ensures ALL activities (global + workflow-specific) are implemented.
@@ -54,28 +49,30 @@ type ActivitiesHandler<TContract extends ContractDefinition> = (TContract["activ
  *
  * @example
  * ```ts
- * import { declareActivitiesHandler, ActivityError } from '@temporal-contract/worker/activity';
+ * import { declareActivitiesHandler, ApplicationFailure } from '@temporal-contract/worker/activity';
  * import { Result, Future } from '@swan-io/boxed';
  * import myContract from './contract';
  *
  * export const activities = declareActivitiesHandler({
  *   contract: myContract,
  *   activities: {
- *     // Activity returns Result instead of throwing
- *     // All technical exceptions must be wrapped in ActivityError for retry policies
+ *     // Activity returns Result instead of throwing.
  *     sendEmail: (args) => {
- *       return Future.make(async resolve => {
+ *       return Future.make(async (resolve) => {
  *         try {
  *           await emailService.send(args);
  *           resolve(Result.Ok({ sent: true }));
  *         } catch (error) {
- *           // Wrap technical errors in ActivityError to enable retries
+ *           // Wrap technical errors in ApplicationFailure. `nonRetryable`
+ *           // is per-instance: set it to true on permanent failures so
+ *           // Temporal stops retrying immediately.
  *           resolve(Result.Error(
- *             new ActivityError(
- *               'EMAIL_SEND_FAILED',
- *               'Failed to send email',
- *               error // Original error as cause for debugging
- *             )
+ *             ApplicationFailure.create({
+ *               type: 'EMAIL_SEND_FAILED',
+ *               message: 'Failed to send email',
+ *               nonRetryable: false,
+ *               cause: error instanceof Error ? error : undefined,
+ *             }),
  *           ));
  *         }
  *       });
@@ -92,8 +89,21 @@ type ActivitiesHandler<TContract extends ContractDefinition> = (TContract["activ
  *   taskQueue: contract.taskQueue,
  * });
  * ```
+ *
+ * @remarks
+ * The wrapper accepts implementations in the
+ * `Future<Result<T, ApplicationFailure>>` shape and produces ordinary
+ * Promise-returning Temporal handlers (Result.Error → thrown
+ * `ApplicationFailure`; Result.Ok → output validated against the
+ * contract and resolved). It does **not** hide Temporal's
+ * `@temporalio/activity` runtime: inside the body you can still call
+ * `Context.current()` from `@temporalio/activity` to access heartbeats
+ * (`heartbeat(details)`, `heartbeatDetails`), activity info (attempt
+ * number, workflow IDs), and the async-completion task token. See the
+ * "Working with the Activity Context" section of the worker
+ * implementation guide for end-to-end examples.
  */
 declare function declareActivitiesHandler<TContract extends ContractDefinition>(options: DeclareActivitiesHandlerOptions<TContract>): ActivitiesHandler<TContract>;
 //#endregion
-export { ActivitiesHandler, ActivityDefinitionNotFoundError, ActivityError, ActivityInputValidationError, ActivityOutputValidationError, declareActivitiesHandler, getWorkflowActivities, getWorkflowActivityNames, getWorkflowNames, isWorkflowActivity };
+export { ActivitiesHandler, ActivityDefinitionNotFoundError, ActivityInputValidationError, ActivityOutputValidationError, ApplicationFailure, declareActivitiesHandler };
 //# sourceMappingURL=activity.d.mts.map

package/dist/activity.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"activity.d.mts","names":[],"sources":["../src/activity.ts"],"mappings":";;;;;;;AA2BA;;;cAAa,aAAA,SAAsB,KAAA;EAAA,SAEf,IAAA;cAAA,IAAA,UAChB,OAAA,UACA,KAAA;AAAA;;;;;;AASH;KAQI,2BAAA,mBAA8C,kBAAA,KACjD,IAAA,EAAM,gBAAA,CAAiB,SAAA,MACpB,MAAA,CAAO,MAAA,CAAO,iBAAA,CAAkB,SAAA,GAAY,aAAA;;;;KAK5C,sCAAA,mBAAyD,kBAAA,KAE3D,SAAA,uBAAgC,MAAA,SAAe,kBAAA,IAC5C,8BAAA,CAA+B,SAAA,8CAIX,SAAA,gBAAyB,SAAA,cAAuB,SAAA,wBAAiC,MAAA,SAEnG,kBAAA,IAEE,8BAAA,CAA+B,SAAA,cAAuB,SAAA;AAAA,KAI3D,8BAAA,qBAAmD,MAAA,SAAe,kBAAA,mBACzD,WAAA,GAAc,2BAAA,CAA4B,WAAA,CAAY,CAAA;;;;KAM/D,+BAAA,mBAAkD,kBAAA;EACrD,QAAA,EAAU,SAAA;EACV,UAAA,EAAY,sCAAA,CAAuC,SAAA;AAAA;AAAA,KAGhD,sBAAA,mBAAyC,kBAAA,KAC5C,IAAA,EAAM,gBAAA,CAAiB,SAAA,MACpB,OAAA,CAAQ,iBAAA,CAAkB,SAAA;AAAA,KAE1B,yBAAA,qBAA8C,MAAA,SAAe,kBAAA,mBACpD,WAAA,GAAc,sBAAA,CAAuB,WAAA,CAAY,CAAA;AAAA,KAG1D,mBAAA,OAA0B,CAAA,oBAAqB,CAAA,EAAG,CAAA,6BACrD,CAAA,sBAEE,CAAA;;;AA3C0D;;;KAmDlD,iBAAA,mBAAoC,kBAAA,KAE7C,SAAA,uBAAgC,MAAA,SAAe,kBAAA,IAC5C,yBAAA,CAA0B,SAAA,wBAG5B,mBAAA,uBAEwB,SAAA,gBAAyB,SAAA,cAAuB,SAAA,wBAAiC,MAAA,SAEnG,kBAAA,IAEE,yBAAA,CAA0B,SAAA,cAAuB,SAAA,8BAE/C,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAjD2D;;;;;;;;;;;;;;;;;;;;;AAKJ;iBAoGrD,wBAAA,mBAA2C,kBAAA,CAAA,CACzD,OAAA,EAAS,+BAAA,CAAgC,SAAA,IACxC,iBAAA,CAAkB,SAAA"}
+{"version":3,"file":"activity.d.mts","names":[],"sources":["../src/activity.ts"],"mappings":";;;;;;AAgCwD;;;;;;;;;AAAA,KAWnD,2BAAA,mBAA8C,kBAAA,KACjD,IAAA,EAAM,gBAAA,CAAiB,SAAA,MACpB,MAAA,CAAO,MAAA,CAAO,iBAAA,CAAkB,SAAA,GAAY,oBAAA;;;;KAK5C,sCAAA,mBAAyD,kBAAA,KAE3D,SAAA,uBAAgC,MAAA,SAAe,kBAAA,IAC5C,8BAAA,CAA+B,SAAA,8CAIX,SAAA,gBAAyB,SAAA,cAAuB,SAAA,wBAAiC,MAAA,SAEnG,kBAAA,IAEE,8BAAA,CAA+B,SAAA,cAAuB,SAAA;AAAA,KAI3D,8BAAA,qBAAmD,MAAA,SAAe,kBAAA,mBACzD,WAAA,GAAc,2BAAA,CAA4B,WAAA,CAAY,CAAA;;;;KAM/D,+BAAA,mBAAkD,kBAAA;EACrD,QAAA,EAAU,SAAA;EACV,UAAA,EAAY,sCAAA,CAAuC,SAAA;AAAA;AAAA,KAGhD,sBAAA,mBAAyC,kBAAA,KAC5C,IAAA,EAAM,gBAAA,CAAiB,SAAA,MACpB,OAAA,CAAQ,iBAAA,CAAkB,SAAA;AAAA,KAE1B,yBAAA,qBAA8C,MAAA,SAAe,kBAAA,mBACpD,WAAA,GAAc,sBAAA,CAAuB,WAAA,CAAY,CAAA;AAAA,KAG1D,mBAAA,OAA0B,CAAA,oBAAqB,CAAA,EAAG,CAAA,6BACrD,CAAA,sBAEE,CAAA;;;;;;KAQQ,iBAAA,mBAAoC,kBAAA,KAE7C,SAAA,uBAAgC,MAAA,SAAe,kBAAA,IAC5C,yBAAA,CAA0B,SAAA,wBAG5B,mBAAA,uBAEwB,SAAA,gBAAyB,SAAA,cAAuB,SAAA,wBAAiC,MAAA,SAEnG,kBAAA,IAEE,yBAAA,CAA0B,SAAA,cAAuB,SAAA,8BAE/C,SAAA;;;;;;;;;;;;;;;;;;;;;;;;AAjD2D;;;;;;;;;;;;;;;;;;;;;AAKJ;;;;;;;;;;;;;;;;;;AAQP;;;;;;iBA2G9C,wBAAA,mBAA2C,kBAAA,CAAA,CACzD,OAAA,EAAS,+BAAA,CAAgC,SAAA,IACxC,iBAAA,CAAkB,SAAA"}