@automate.ax/client 0.98.0 → 0.99.0

package/README.md

@@ -42,7 +42,19 @@ List procedures return `{ items, pageInfo }`. When `pageInfo.hasMore` is true, p
 
 The key is organization-owned and is sent in the `x-api-key` header. It does not represent a user session.
 
-The client targets `https://automate.ax/api/rpc`.
+The client targets `https://automate.ax/api/rpc`. Embedded and local callers can override `rpcUrl`, provide a custom `fetch`, and add per-request `headers`:
+
+```ts
+const client = createAutomateClient({
+  apiKey: process.env.AUTOMATE_AX_API_KEY!,
+  rpcUrl: "https://automate.test/api/rpc",
+  headers: () => ({ "x-request-source": "local-test" }),
+})
+```
+
+Authentication headers are set after additional headers and cannot be overridden through `headers`.
+
+Automate.ax action runtimes use the same client with `runtimeToken`. This mode is for the active execution token supplied by the platform; it is not a replacement for an organization API key in external applications.
 
 ## User session
 
@@ -63,4 +75,4 @@ const manifest = await client.executionData.manifest({
 console.log(manifest.consistency, manifest.resources)
 ```
 
-Credential callbacks are evaluated before every request, so a client can use a refreshed token without being recreated. Supply either `apiKey` or `sessionToken`.
+Credential callbacks are evaluated before every request, so a client can use a refreshed token without being recreated. Supply exactly one of `apiKey`, `runtimeToken`, or `sessionToken`.

package/dist/index.d.ts

@@ -2,15 +2,31 @@ import type { publicContract } from "@automate.ax/api-contract";
 import type { ContractRouterClient } from "@orpc/contract";
 export type AutomateClient = ContractRouterClient<typeof publicContract>;
 type ClientCredential = string | (() => Promise<string | null | undefined> | string | null | undefined);
-export type AutomateClientOptions = {
+type HeaderInput = ConstructorParameters<typeof Headers>[0];
+interface AutomateClientTransportOptions {
+    /** Additional request headers merged before authentication headers. */
+    headers?: HeaderInput | (() => Promise<HeaderInput> | HeaderInput);
+    /** Custom fetch transport, primarily for embedded and local environments. */
+    fetch?: (request: Request, init?: RequestInit) => Promise<Response>;
+    /** Automate.ax RPC endpoint. Defaults to the production API. */
+    rpcUrl?: string | URL;
+}
+export type AutomateClientOptions = AutomateClientTransportOptions & ({
     /** Automate.ax organization API key sent through `x-api-key`. */
     apiKey: ClientCredential;
+    runtimeToken?: never;
     sessionToken?: never;
 } | {
     apiKey?: never;
+    /** Active Automate.ax execution token sent through `x-api-key`. */
+    runtimeToken: ClientCredential;
+    sessionToken?: never;
+} | {
+    apiKey?: never;
+    runtimeToken?: never;
     /** Automate.ax user-session bearer token. */
     sessionToken: ClientCredential;
-};
+});
 /**
  * Creates a type-safe client for the public management API.
  *

package/dist/index.js

@@ -11,13 +11,27 @@ const RPC_URL = "https://automate.ax/api/rpc";
  */
 export function createAutomateClient(options) {
     return createORPCClient(new RPCLink({
-        url: RPC_URL,
+        fetch: async (request, init) => await (options.fetch ?? globalThis.fetch)(request, {
+            ...init,
+            credentials: "omit",
+        }),
+        url: options.rpcUrl ?? RPC_URL,
         headers: async () => {
-            const headers = new Headers();
-            const credential = options.apiKey ?? options.sessionToken;
+            const headers = new Headers(typeof options.headers === "function"
+                ? await options.headers()
+                : options.headers);
+            const usesKey = "apiKey" in options || "runtimeToken" in options;
+            const credential = "apiKey" in options
+                ? options.apiKey
+                : "runtimeToken" in options
+                    ? options.runtimeToken
+                    : options.sessionToken;
             const value = typeof credential === "function" ? await credential() : credential;
+            headers.delete("authorization");
+            headers.delete("cookie");
+            headers.delete("x-api-key");
             if (value) {
-                headers.set(options.apiKey === undefined ? "authorization" : "x-api-key", options.apiKey === undefined ? `Bearer ${value}` : value);
+                headers.set(usesKey ? "x-api-key" : "authorization", usesKey ? value : `Bearer ${value}`);
             }
             return headers;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automate.ax/client",
-  "version": "0.98.0",
+  "version": "0.99.0",
   "description": "Type-safe client for the Automate.ax API.",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,7 @@
     }
   },
   "dependencies": {
-    "@automate.ax/api-contract": "0.98.0",
+    "@automate.ax/api-contract": "0.99.0",
     "@orpc/client": "1.15.0",
     "@orpc/contract": "1.15.0"
   },

package/src/index.ts

@@ -12,18 +12,42 @@ type ClientCredential =
   | string
   | (() => Promise<string | null | undefined> | string | null | undefined)
 
-export type AutomateClientOptions =
-  | {
-      /** Automate.ax organization API key sent through `x-api-key`. */
-      apiKey: ClientCredential
-      sessionToken?: never
-    }
-  | {
-      apiKey?: never
-
-      /** Automate.ax user-session bearer token. */
-      sessionToken: ClientCredential
-    }
+type HeaderInput = ConstructorParameters<typeof Headers>[0]
+
+interface AutomateClientTransportOptions {
+  /** Additional request headers merged before authentication headers. */
+  headers?: HeaderInput | (() => Promise<HeaderInput> | HeaderInput)
+
+  /** Custom fetch transport, primarily for embedded and local environments. */
+  fetch?: (request: Request, init?: RequestInit) => Promise<Response>
+
+  /** Automate.ax RPC endpoint. Defaults to the production API. */
+  rpcUrl?: string | URL
+}
+
+export type AutomateClientOptions = AutomateClientTransportOptions &
+  (
+    | {
+        /** Automate.ax organization API key sent through `x-api-key`. */
+        apiKey: ClientCredential
+        runtimeToken?: never
+        sessionToken?: never
+      }
+    | {
+        apiKey?: never
+
+        /** Active Automate.ax execution token sent through `x-api-key`. */
+        runtimeToken: ClientCredential
+        sessionToken?: never
+      }
+    | {
+        apiKey?: never
+        runtimeToken?: never
+
+        /** Automate.ax user-session bearer token. */
+        sessionToken: ClientCredential
+      }
+  )
 
 /**
  * Creates a type-safe client for the public management API.
@@ -38,17 +62,36 @@ export function createAutomateClient(
 ): AutomateClient {
   return createORPCClient(
     new RPCLink({
-      url: RPC_URL,
+      fetch: async (request, init) =>
+        await (options.fetch ?? globalThis.fetch)(request, {
+          ...init,
+          credentials: "omit",
+        }),
+      url: options.rpcUrl ?? RPC_URL,
       headers: async () => {
-        const headers = new Headers()
-        const credential = options.apiKey ?? options.sessionToken
+        const headers = new Headers(
+          typeof options.headers === "function"
+            ? await options.headers()
+            : options.headers,
+        )
+        const usesKey = "apiKey" in options || "runtimeToken" in options
+        const credential =
+          "apiKey" in options
+            ? options.apiKey
+            : "runtimeToken" in options
+              ? options.runtimeToken
+              : options.sessionToken
         const value =
           typeof credential === "function" ? await credential() : credential
 
+        headers.delete("authorization")
+        headers.delete("cookie")
+        headers.delete("x-api-key")
+
         if (value) {
           headers.set(
-            options.apiKey === undefined ? "authorization" : "x-api-key",
-            options.apiKey === undefined ? `Bearer ${value}` : value,
+            usesKey ? "x-api-key" : "authorization",
+            usesKey ? value : `Bearer ${value}`,
           )
         }