@turnkey/http 0.6.0 → 0.7.1-beta.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @turnkey/http
 
+## 0.7.0
+
+### Minor Changes
+
+- Improved documentation
+- Added `withAsyncPolling(...)` helper to provide built-in async polling support. Read more:
+  - https://github.com/tkhq/sdk/tree/main/packages/http#withasyncpolling-helper
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -30,3 +30,58 @@ const data = await PublicApiService.postGetWhoami({
   },
 });
 ```
+
+## HTTP fetchers
+
+`@turnkey/http` provides fully typed http fetchers for interacting with the Turnkey API. You can find all available methods [here](/packages/http/src/__generated__/services/coordinator/public/v1/public_api.fetcher.ts). The types of input parameters and output responses are also exported for convenience.
+
+The OpenAPI spec that generates all fetchers is also [included](/packages/http/src/__generated__/services/coordinator/public/v1/public_api.swagger.json) in the package.
+
+## `withAsyncPolling(...)` helper
+
+All Turnkey mutation endpoints are asynchronous (with the exception of signing endpoints). To help you simplify async mutations, `@turnkey/http` provides a `withAsyncPolling(...)` wrapper. Here's a quick example:
+
+```typescript
+import {
+  PublicApiService,
+  withAsyncPolling,
+  TurnkeyActivityError,
+} from "@turnkey/http";
+
+// Use `withAsyncPolling(...)` to wrap & create a fetcher with built-in async polling support
+const fetcher = withAsyncPolling({
+  request: PublicApiService.postCreatePrivateKeys,
+});
+
+// The fetcher remains fully typed. After submitting the request,
+// it'll poll until the activity reaches a terminal state.
+try {
+  const activity = await fetcher({
+    body: {
+      /* ... */
+    },
+  });
+
+  // Success!
+  console.log(activity.result.createPrivateKeysResult?.privateKeyIds?.[0]);
+} catch (error) {
+  if (error instanceof TurnkeyActivityError) {
+    // In case the activity is rejected, failed, or requires consensus,
+    // a rich `TurnkeyActivityError` will be thrown. You can read from
+    // `TurnkeyActivityError` to find out why the activity didn't succeed.
+    //
+    // For instance, if your activity requires consensus and doesn't have
+    // enough approvals, you can get the `activityId` from `TurnkeyActivityError`,
+    // store it somewhere, then re-fetch the activity via `.postGetActivity(...)`
+    // when the required approvals/rejections are in place.
+  }
+}
+```
+
+## More examples
+
+See [`createNewEthereumPrivateKey.ts`](/examples/with-ethers/src/createNewEthereumPrivateKey.ts) in the [`with-ethers`](/examples/with-ethers/) example.
+
+## See also
+
+- [`@turnkey/ethers`](/packages/ethers/): higher-level Turnkey Signer for [`Ethers`](https://docs.ethers.org/v5/api/signer/)

package/dist/async.d.ts

@@ -0,0 +1,13 @@
+import { TActivityResponse } from "./shared";
+/**
+ * Wraps a request to create a fetcher with built-in async polling support.
+ *
+ * {@link https://github.com/tkhq/sdk/blob/main/packages/http/README.md#withasyncpolling-helper}
+ */
+export declare function withAsyncPolling<O extends TActivityResponse, I extends {
+    body: unknown;
+}>(params: {
+    request: (input: I) => Promise<O>;
+    refreshIntervalMs?: number;
+}): (input: I) => Promise<O["activity"]>;
+//# sourceMappingURL=async.d.ts.map

package/dist/async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../src/async.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,iBAAiB,EAAwB,MAAM,UAAU,CAAC;AAI9E;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,SAAS,iBAAiB,EAC3B,CAAC,SAAS;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,EAC3B,MAAM,EAAE;IACR,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAClC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAqEvC"}

package/dist/async.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAsyncPolling = void 0;
+const barrel_1 = require("./__generated__/barrel");
+const shared_1 = require("./shared");
+const DEFAULT_REFRESH_INTERVAL_MS = 500;
+/**
+ * Wraps a request to create a fetcher with built-in async polling support.
+ *
+ * {@link https://github.com/tkhq/sdk/blob/main/packages/http/README.md#withasyncpolling-helper}
+ */
+function withAsyncPolling(params) {
+    const { request, refreshIntervalMs = DEFAULT_REFRESH_INTERVAL_MS } = params;
+    return async (input) => {
+        const initialResponse = await request(input);
+        let activity = initialResponse.activity;
+        while (true) {
+            switch (activity.status) {
+                case "ACTIVITY_STATUS_COMPLETED": {
+                    return activity;
+                }
+                case "ACTIVITY_STATUS_CREATED": {
+                    // Async pending state -- keep polling
+                    break;
+                }
+                case "ACTIVITY_STATUS_PENDING": {
+                    // Async pending state -- keep polling
+                    break;
+                }
+                case "ACTIVITY_STATUS_CONSENSUS_NEEDED": {
+                    // If the activity requires consensus, we shouldn't be polling forever.
+                    // You can read the `TurnkeyActivityError` thrown to get the `activityId`,
+                    // store it somewhere, then re-fetch the activity via `.postGetActivity(...)`
+                    // when the required approvals/rejections are in place.
+                    throw new shared_1.TurnkeyActivityError({
+                        message: `Consensus needed for activity ${activity.id}`,
+                        activityId: activity.id,
+                        activityStatus: activity.status,
+                        activityType: activity.type,
+                    });
+                }
+                case "ACTIVITY_STATUS_FAILED": {
+                    // Activity failed
+                    throw new shared_1.TurnkeyActivityError({
+                        message: `Activity ${activity.id} failed`,
+                        activityId: activity.id,
+                        activityStatus: activity.status,
+                        activityType: activity.type,
+                    });
+                }
+                case "ACTIVITY_STATUS_REJECTED": {
+                    // Activity was rejected
+                    throw new shared_1.TurnkeyActivityError({
+                        message: `Activity ${activity.id} was rejected`,
+                        activityId: activity.id,
+                        activityStatus: activity.status,
+                        activityType: activity.type,
+                    });
+                }
+                default: {
+                    // Make sure the switch block is exhaustive
+                    assertNever(activity.status);
+                }
+            }
+            await sleep(refreshIntervalMs);
+            const pollingResponse = await barrel_1.PublicApiService.postGetActivity({
+                body: {
+                    activityId: activity.id,
+                    organizationId: activity.organizationId,
+                },
+            });
+            activity = pollingResponse.activity;
+        }
+    };
+}
+exports.withAsyncPolling = withAsyncPolling;
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(() => {
+            resolve();
+        }, ms);
+    });
+}
+function assertNever(input, message) {
+    throw new Error(message != null ? message : `Unexpected case: ${JSON.stringify(input)}`);
+}
+//# sourceMappingURL=async.js.map

package/dist/async.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.js","sourceRoot":"","sources":["../src/async.ts"],"names":[],"mappings":";;;AAAA,mDAA0D;AAC1D,qCAA8E;AAE9E,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAExC;;;;GAIG;AACH,SAAgB,gBAAgB,CAG9B,MAGD;IACC,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,2BAA2B,EAAE,GAAG,MAAM,CAAC;IAE5E,OAAO,KAAK,EAAE,KAAQ,EAAE,EAAE;QACxB,MAAM,eAAe,GAAsB,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;QAChE,IAAI,QAAQ,GAAc,eAAe,CAAC,QAAQ,CAAC;QAEnD,OAAO,IAAI,EAAE;YACX,QAAQ,QAAQ,CAAC,MAAM,EAAE;gBACvB,KAAK,2BAA2B,CAAC,CAAC;oBAChC,OAAO,QAAQ,CAAC;iBACjB;gBACD,KAAK,yBAAyB,CAAC,CAAC;oBAC9B,sCAAsC;oBACtC,MAAM;iBACP;gBACD,KAAK,yBAAyB,CAAC,CAAC;oBAC9B,sCAAsC;oBACtC,MAAM;iBACP;gBACD,KAAK,kCAAkC,CAAC,CAAC;oBACvC,uEAAuE;oBACvE,0EAA0E;oBAC1E,6EAA6E;oBAC7E,uDAAuD;oBACvD,MAAM,IAAI,6BAAoB,CAAC;wBAC7B,OAAO,EAAE,iCAAiC,QAAQ,CAAC,EAAE,EAAE;wBACvD,UAAU,EAAE,QAAQ,CAAC,EAAE;wBACvB,cAAc,EAAE,QAAQ,CAAC,MAAM;wBAC/B,YAAY,EAAE,QAAQ,CAAC,IAAI;qBAC5B,CAAC,CAAC;iBACJ;gBACD,KAAK,wBAAwB,CAAC,CAAC;oBAC7B,kBAAkB;oBAClB,MAAM,IAAI,6BAAoB,CAAC;wBAC7B,OAAO,EAAE,YAAY,QAAQ,CAAC,EAAE,SAAS;wBACzC,UAAU,EAAE,QAAQ,CAAC,EAAE;wBACvB,cAAc,EAAE,QAAQ,CAAC,MAAM;wBAC/B,YAAY,EAAE,QAAQ,CAAC,IAAI;qBAC5B,CAAC,CAAC;iBACJ;gBACD,KAAK,0BAA0B,CAAC,CAAC;oBAC/B,wBAAwB;oBACxB,MAAM,IAAI,6BAAoB,CAAC;wBAC7B,OAAO,EAAE,YAAY,QAAQ,CAAC,EAAE,eAAe;wBAC/C,UAAU,EAAE,QAAQ,CAAC,EAAE;wBACvB,cAAc,EAAE,QAAQ,CAAC,MAAM;wBAC/B,YAAY,EAAE,QAAQ,CAAC,IAAI;qBAC5B,CAAC,CAAC;iBACJ;gBACD,OAAO,CAAC,CAAC;oBACP,2CAA2C;oBAC3C,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;iBAC9B;aACF;YAED,MAAM,KAAK,CAAC,iBAAiB,CAAC,CAAC;YAE/B,MAAM,eAAe,GACnB,MAAM,yBAAgB,CAAC,eAAe,CAAC;gBACrC,IAAI,EAAE;oBACJ,UAAU,EAAE,QAAQ,CAAC,EAAE;oBACvB,cAAc,EAAE,QAAQ,CAAC,cAAc;iBACxC;aACF,CAAC,CAAC;YAEL,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC;SACrC;IACH,CAAC,CAAC;AACJ,CAAC;AA3ED,4CA2EC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,UAAU,CAAC,GAAG,EAAE;YACd,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;IACT,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,WAAW,CAAC,KAAY,EAAE,OAAgB;IACjD,MAAM,IAAI,KAAK,CACb,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CACxE,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./__generated__/barrel";
 export { init } from "./config";
+export { TurnkeyActivityError } from "./shared";
+export { withAsyncPolling } from "./async";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AAEvC,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AAEvC,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -14,8 +14,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.init = void 0;
+exports.withAsyncPolling = exports.TurnkeyActivityError = exports.init = void 0;
 __exportStar(require("./__generated__/barrel"), exports);
 var config_1 = require("./config");
 Object.defineProperty(exports, "init", { enumerable: true, get: function () { return config_1.init; } });
+var shared_1 = require("./shared");
+Object.defineProperty(exports, "TurnkeyActivityError", { enumerable: true, get: function () { return shared_1.TurnkeyActivityError; } });
+var async_1 = require("./async");
+Object.defineProperty(exports, "withAsyncPolling", { enumerable: true, get: function () { return async_1.withAsyncPolling; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,yDAAuC;AAEvC,mCAAgC;AAAvB,8FAAA,IAAI,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,yDAAuC;AAEvC,mCAAgC;AAAvB,8FAAA,IAAI,OAAA;AAEb,mCAAgD;AAAvC,8GAAA,oBAAoB,OAAA;AAE7B,iCAA2C;AAAlC,yGAAA,gBAAgB,OAAA"}

package/dist/shared.d.ts

@@ -0,0 +1,20 @@
+import type { definitions } from "./__generated__/services/coordinator/public/v1/public_api.types";
+export type TActivity = definitions["v1Activity"];
+export type TActivityResponse = definitions["v1ActivityResponse"];
+export type TActivityId = TActivity["id"];
+export type TActivityStatus = TActivity["status"];
+export type TActivityType = TActivity["type"];
+export declare class TurnkeyActivityError extends Error {
+    activityId: TActivityId | null;
+    activityStatus: TActivityStatus | null;
+    activityType: TActivityType | null;
+    cause: Error | null;
+    constructor(input: {
+        message: string;
+        cause?: Error | null;
+        activityId?: TActivityId | null;
+        activityStatus?: TActivityStatus | null;
+        activityType?: TActivityType | null;
+    });
+}
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iEAAiE,CAAC;AAEnG,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;AAC1C,MAAM,MAAM,eAAe,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAClD,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;AAE9C,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,UAAU,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/B,cAAc,EAAE,eAAe,GAAG,IAAI,CAAC;IACvC,YAAY,EAAE,aAAa,GAAG,IAAI,CAAC;IACnC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;gBAER,KAAK,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB,UAAU,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;QAChC,cAAc,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;QACxC,YAAY,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;KACrC;CAUF"}

package/dist/shared.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TurnkeyActivityError = void 0;
+class TurnkeyActivityError extends Error {
+    constructor(input) {
+        const { message, cause, activityId, activityStatus, activityType } = input;
+        super(message);
+        this.name = "TurnkeyActivityError";
+        this.activityId = activityId ?? null;
+        this.activityStatus = activityStatus ?? null;
+        this.activityType = activityType ?? null;
+        this.cause = cause ?? null;
+    }
+}
+exports.TurnkeyActivityError = TurnkeyActivityError;
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":";;;AAQA,MAAa,oBAAqB,SAAQ,KAAK;IAM7C,YAAY,KAMX;QACC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC;QAC3E,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,UAAU,IAAI,IAAI,CAAC;QACrC,IAAI,CAAC,cAAc,GAAG,cAAc,IAAI,IAAI,CAAC;QAC7C,IAAI,CAAC,YAAY,GAAG,YAAY,IAAI,IAAI,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,KAAK,IAAI,IAAI,CAAC;IAC7B,CAAC;CACF;AAtBD,oDAsBC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turnkey/http",
-  "version": "0.6.0",
+  "version": "0.7.1-beta.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "license": "Apache-2.0",
@@ -36,6 +36,6 @@
     "build": "tsc",
     "clean": "rimraf ./dist",
     "test": "jest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc -p tsconfig.typecheck.json"
   }
 }