feedback: update errors and changelogs

.changeset/orange-beers-smash.md

@@ -5,5 +5,23 @@
 
 Support activity polling (e.g. for awaiting consensus)
 
-- Add an `activityPoller` parameter for configuring polling behavior
+- [Breaking] Update the `activityPoller` parameter for configuring polling behavior
 - Polling continues until either a max number of retries is reached, or if the activity hits a terminal status
+
+The shape of the parameter has gone from:
+
+```
+{
+  duration: number;
+  timeout: number;
+}
+```
+
+to
+
+```
+{
+  intervalMs: number;
+  numRetries: number;
+}
+```

.changeset/tasty-feet-provide.md

@@ -6,7 +6,7 @@ Add new helpers and update types and errors
 
 - `getSignatureFromActivity` returns the signature corresponding to a completed activity
 - `getSignedTransactionFromActivity` returns the signed transaction corresponding to a completed activity
-- `checkActivityStatus` checks the state of an activity and throws an error if the activity either requires consensus or is otherwise not yet completed
+- `assertActivityCompleted` checks the state of an activity and throws an error if the activity either requires consensus or is otherwise not yet completed
 - `TERMINAL_ACTIVITY_STATUSES` is a const containing all terminal activity statuses. Useful for checking on an activity
 - `TurnkeyActivityError` now uses `undefined` instead of `null`
 - Export some additional types: `TActivity`, `TActivityId`, `TActivityStatus`, `TActivityType`

examples/with-ethers/src/index.ts

@@ -35,13 +35,13 @@ async function main() {
     defaultOrganizationId: process.env.ORGANIZATION_ID!,
     // The following config is useful in contexts where an activity requires consensus.
     // By default, if the activity is not initially successful, it will poll a maximum
-    // of 3 times with an interval of 10000 milliseconds.
+    // of 3 times with an interval of 1000 milliseconds. Otherwise, use the values below.
     //
     // -----
     //
     // activityPoller: {
-    //   intervalMs: 10_000,
-    //   numRetries: 5,
+    //   intervalMs: 5_000,
+    //   numRetries: 10,
     // },
   });
 

examples/with-solana/src/index.ts

@@ -38,13 +38,13 @@ async function main() {
     defaultOrganizationId: organizationId,
     // The following config is useful in contexts where an activity requires consensus.
     // By default, if the activity is not initially successful, it will poll a maximum
-    // of 3 times with an interval of 10000 milliseconds.
+    // of 3 times with an interval of 1000 milliseconds. Otherwise, use the values below.
     //
     // -----
     //
     // activityPoller: {
-    //   intervalMs: 10_000,
-    //   numRetries: 5,
+    //   intervalMs: 5_000,
+    //   numRetries: 10,
     // },
   });
 

packages/ethers/src/index.ts

@@ -21,7 +21,7 @@ import {
   TurnkeyActivityError,
   TurnkeyRequestError,
   TurnkeyActivityConsensusNeededError,
-  checkActivityStatus,
+  assertActivityCompleted,
   assertNonNull,
   type TSignature,
 } from "@turnkey/http";
@@ -120,7 +120,7 @@ export class TurnkeySigner extends AbstractSigner implements ethers.Signer {
         timestampMs: String(Date.now()), // millisecond timestamp
       });
 
-      checkActivityStatus({
+      assertActivityCompleted({
         id: activity.id,
         status: activity.status,
       });
@@ -137,7 +137,7 @@ export class TurnkeySigner extends AbstractSigner implements ethers.Signer {
         }
       );
 
-      checkActivityStatus({
+      assertActivityCompleted({
         id: activity.id,
         status: activity.status,
       });
@@ -254,22 +254,21 @@ export class TurnkeySigner extends AbstractSigner implements ethers.Signer {
         timestampMs: String(Date.now()), // millisecond timestamp
       });
 
-      checkActivityStatus({
+      assertActivityCompleted({
         id: activity.id,
         status: activity.status,
       });
 
       result = assertNonNull(activity?.result?.signRawPayloadResult);
     } else {
-      // const trying = this.client as TurnkeyClient;
       const { activity, r, s, v } = await this.client.signRawPayload({
         signWith: this.signWith,
         payload: message,
         encoding: "PAYLOAD_ENCODING_HEXADECIMAL",
         hashFunction: "HASH_FUNCTION_NO_OP",
       });
 
-      checkActivityStatus({
+      assertActivityCompleted({
         id: activity.id,
         status: activity.status,
       });

packages/http/src/index.ts

@@ -6,10 +6,11 @@ export { init, browserInit } from "./config";
 export { TurnkeyRequestError } from "./base";
 export {
   assertNonNull,
-  checkActivityStatus,
+  assertActivityCompleted,
   getSignatureFromActivity,
   getSignaturesFromActivity,
   getSignedTransactionFromActivity,
+  InvalidArgumentError,
   TurnkeyActivityError,
   TurnkeyActivityConsensusNeededError,
   type TActivity,

packages/http/src/shared.ts

@@ -57,7 +57,31 @@ export class TurnkeyActivityConsensusNeededError extends Error {
   }
 }
 
-export function checkActivityStatus(input: {
+export class InvalidArgumentError extends Error {
+  activityId: TActivityId | undefined;
+  activityStatus: TActivityStatus | undefined;
+  activityType: TActivityType | undefined;
+  cause: Error | undefined;
+
+  constructor(input: {
+    message: string;
+    cause?: Error | undefined;
+    activityId?: TActivityId | undefined;
+    activityStatus?: TActivityStatus | undefined;
+    activityType?: TActivityType | undefined;
+  }) {
+    const { message, cause, activityId, activityStatus, activityType } = input;
+    super(message);
+
+    this.name = "InvalidArgumentError";
+    this.activityId = activityId ?? undefined;
+    this.activityStatus = activityStatus ?? undefined;
+    this.activityType = activityType ?? undefined;
+    this.cause = cause ?? undefined;
+  }
+}
+
+export function assertActivityCompleted(input: {
   id: string;
   status: TActivityStatus;
 }) {
@@ -114,14 +138,14 @@ export function getSignatureFromActivity(activity: TActivity): TSignature {
       "ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2",
     ].includes(activity.type)
   ) {
-    throw new TurnkeyActivityError({
-      message: `Unexpected activity type: ${activity.type}`,
+    throw new InvalidArgumentError({
+      message: `Cannot get signature from activity type: ${activity.type}`,
       activityId: activity.id,
       activityStatus: activity.status,
     });
   }
 
-  checkActivityStatus({
+  assertActivityCompleted({
     id: activity.id,
     status: activity.status,
   });
@@ -140,14 +164,14 @@ export function getSignatureFromActivity(activity: TActivity): TSignature {
  */
 export function getSignaturesFromActivity(activity: TActivity): TSignature[] {
   if (!["ACTIVITY_TYPE_SIGN_RAW_PAYLOADS"].includes(activity.type)) {
-    throw new TurnkeyActivityError({
-      message: `Unexpected activity type: ${activity.type}`,
+    throw new InvalidArgumentError({
+      message: `Cannot get signature from activity type: ${activity.type}`,
       activityId: activity.id,
       activityStatus: activity.status,
     });
   }
 
-  checkActivityStatus({
+  assertActivityCompleted({
     id: activity.id,
     status: activity.status,
   });
@@ -173,14 +197,14 @@ export function getSignedTransactionFromActivity(
       "ACTIVITY_TYPE_SIGN_TRANSACTION_V2",
     ].includes(activity.type)
   ) {
-    throw new TurnkeyActivityError({
-      message: `Unexpected activity type: ${activity.type}`,
+    throw new InvalidArgumentError({
+      message: `Cannot get signed transaction from activity type: ${activity.type}`,
       activityId: activity.id,
       activityStatus: activity.status,
     });
   }
 
-  checkActivityStatus({
+  assertActivityCompleted({
     id: activity.id,
     status: activity.status,
   });

packages/sdk-browser/scripts/codegen.js

@@ -244,10 +244,12 @@ const generateSDKClientFromSwagger = async (swaggerSpec, targetPath) => {
   /** @type {Array<string>} */
   const imports = [];
 
-  imports.push('import { TERMINAL_ACTIVITY_STATUSES } from "@turnkey/http";');
+  imports.push(
+    'import { TERMINAL_ACTIVITY_STATUSES, TActivityStatus } from "@turnkey/http";'
+  );
 
   imports.push(
-    'import { GrpcStatus, TurnkeyRequestError, ActivityResponse, TurnkeySDKClientConfig, TActivityStatus } from "../__types__/base";'
+    'import { GrpcStatus, TurnkeyRequestError, ActivityResponse, TurnkeySDKClientConfig } from "../__types__/base";'
   );
 
   imports.push('import { VERSION } from "../__generated__/version";');

packages/sdk-browser/src/__types__/base.ts

@@ -1,4 +1,4 @@
-import type { TActivityId, TurnkeyApiTypes } from "@turnkey/http";
+import type { TActivityId, TActivityStatus } from "@turnkey/http";
 
 export type GrpcStatus = {
   message: string;
@@ -25,13 +25,6 @@ export type THttpConfig = {
   baseUrl: string;
 };
 
-export type TActivityPollerConfig = {
-  intervalMs: number;
-  numRetries: number;
-};
-
-export type TActivityStatus = TurnkeyApiTypes["v1ActivityStatus"];
-
 export class TurnkeyRequestError extends Error {
   details: any[] | null;
   code: number;
@@ -66,6 +59,11 @@ export interface ActivityMetadata {
   };
 }
 
+export type TActivityPollerConfig = {
+  intervalMs: number;
+  numRetries: number;
+};
+
 interface BaseSDKClientConfig {
   apiBaseUrl: string;
   organizationId: string;

packages/sdk-browser/src/index.ts

@@ -41,7 +41,6 @@ import {
 } from "./turnkey-helpers";
 
 import type {
-  TActivityStatus,
   TurnkeySDKClientConfig,
   TurnkeySDKBrowserConfig,
 } from "./__types__/base";
@@ -63,7 +62,6 @@ export {
 
 // Types
 export type {
-  TActivityStatus,
   TApiKeyStamperConfig,
   TIframeStamperConfig,
   TSignedRequest,

packages/sdk-server/scripts/codegen.js

@@ -244,10 +244,12 @@ const generateSDKClientFromSwagger = async (swaggerSpec, targetPath) => {
   /** @type {Array<string>} */
   const imports = [];
 
-  imports.push('import { TERMINAL_ACTIVITY_STATUSES } from "@turnkey/http";');
+  imports.push(
+    'import { TERMINAL_ACTIVITY_STATUSES, TActivityStatus } from "@turnkey/http";'
+  );
 
   imports.push(
-    'import { GrpcStatus, TurnkeyRequestError, ActivityResponse, TurnkeySDKClientConfig, TActivityStatus } from "../__types__/base";'
+    'import { GrpcStatus, TurnkeyRequestError, ActivityResponse, TurnkeySDKClientConfig } from "../__types__/base";'
   );
 
   imports.push('import { VERSION } from "../__generated__/version";');

packages/sdk-server/src/__types__/base.ts

@@ -1,4 +1,4 @@
-import type { TActivityId, TurnkeyApiTypes } from "@turnkey/http";
+import type { TActivityId, TActivityStatus } from "@turnkey/http";
 
 export type GrpcStatus = {
   message: string;
@@ -25,11 +25,6 @@ export type THttpConfig = {
   baseUrl: string;
 };
 
-export type TActivityPollerConfig = {
-  intervalMs: number;
-  numRetries: number;
-};
-
 export class TurnkeyRequestError extends Error {
   details: any[] | null;
   code: number;
@@ -73,6 +68,11 @@ export type commandOverrideParams = {
   timestampMs?: string;
 };
 
+export type TActivityPollerConfig = {
+  intervalMs: number;
+  numRetries: number;
+};
+
 export interface TurnkeySDKClientConfig {
   stamper: TStamper;
   apiBaseUrl: string;
@@ -92,8 +92,6 @@ export interface TurnkeyProxyHandlerConfig {
   allowedMethods?: string[];
 }
 
-export type TActivityStatus = TurnkeyApiTypes["v1ActivityStatus"];
-
 export interface NextApiRequest {
   body: any;
   query: { [key: string]: string };

packages/sdk-server/src/index.ts

@@ -30,7 +30,6 @@ import type {
   TurnkeySDKClientConfig,
   TurnkeySDKServerConfig,
   TurnkeyProxyHandlerConfig,
-  TActivityStatus,
 } from "./__types__/base";
 
 import type * as TurnkeySDKApiTypes from "./__generated__/sdk_api_types";
@@ -49,7 +48,6 @@ export {
 
 // Types
 export type {
-  TActivityStatus,
   TApiKeyStamperConfig,
   TSignedRequest,
   TurnkeyApiTypes,