@voyantjs/cloud-sdk 0.5.0 → 0.6.1

package/README.md

@@ -36,6 +36,49 @@ const vaults = await client.vault.listVaults();
 const phoneNumbers = await client.sms.listPhoneNumbers();
 ```
 
+### From env / worker bindings
+
+`getVoyantCloudClient` reads `VOYANT_CLOUD_API_KEY` (and optionally
+`VOYANT_CLOUD_API_URL`, `VOYANT_CLOUD_USER_AGENT`) from a bindings/env
+object and constructs a client. It throws a typed `VoyantCloudConfigError`
+when the key is missing.
+
+```ts
+import { getVoyantCloudClient, type VoyantCloudEnv } from "@voyantjs/cloud-sdk";
+
+// Cloudflare Worker
+export default {
+  async fetch(_req: Request, env: VoyantCloudEnv) {
+    const cloud = getVoyantCloudClient(env);
+    return Response.json(await cloud.vault.listVaults());
+  },
+};
+```
+
+```ts
+import { getVoyantCloudClient } from "@voyantjs/cloud-sdk";
+
+// Node
+const cloud = getVoyantCloudClient(process.env);
+const vaults = await cloud.vault.listVaults();
+```
+
+`overrides` win over env values, except an empty-string override is
+treated as missing so it can't silently clobber a valid env value:
+
+```ts
+import { getVoyantCloudClient, type VoyantCloudEnv } from "@voyantjs/cloud-sdk";
+
+declare const env: VoyantCloudEnv;
+declare const tenantKey: string;
+
+const cloud = getVoyantCloudClient(env, { apiKey: tenantKey });
+```
+
+For paths that legitimately operate without cloud (local dev tooling that
+doesn't send mail, etc.), use `tryGetVoyantCloudClient` — it returns
+`null` instead of throwing when the key is unset.
+
 ## Shape
 
 Root groups:

package/dist/env.d.ts

@@ -0,0 +1,41 @@
+import { VoyantCloudClient } from "./client.js";
+import type { VoyantCloudClientOptions } from "./types.js";
+/**
+ * Bindings/env shape recognized by {@link getVoyantCloudClient} and
+ * {@link tryGetVoyantCloudClient}.
+ *
+ * Designed to accept a Cloudflare Worker `env` object, Node `process.env`,
+ * or any other key/value bag of strings. Empty-string values are treated
+ * the same as `undefined` — common when `.env` files leave a key blank.
+ */
+export interface VoyantCloudEnv {
+    VOYANT_CLOUD_API_KEY?: string;
+    VOYANT_CLOUD_API_URL?: string;
+    VOYANT_CLOUD_USER_AGENT?: string;
+}
+/**
+ * Thrown when {@link getVoyantCloudClient} cannot construct a client because
+ * `VOYANT_CLOUD_API_KEY` is missing and no override was supplied.
+ */
+export declare class VoyantCloudConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Construct a {@link VoyantCloudClient} from a runtime bindings object
+ * (Cloudflare Worker `env`, Node `process.env`, etc.).
+ *
+ * `overrides` take precedence over env values, except an empty-string
+ * override is treated as missing so it can't silently clobber a valid env
+ * value.
+ *
+ * Throws {@link VoyantCloudConfigError} when no API key can be resolved
+ * from either source.
+ */
+export declare function getVoyantCloudClient(env: VoyantCloudEnv, overrides?: Partial<VoyantCloudClientOptions>): VoyantCloudClient;
+/**
+ * Like {@link getVoyantCloudClient}, but returns `null` when the API key
+ * is unset instead of throwing. Use from edges that legitimately operate
+ * without cloud (e.g. local dev tooling that doesn't send mail).
+ */
+export declare function tryGetVoyantCloudClient(env: VoyantCloudEnv, overrides?: Partial<VoyantCloudClientOptions>): VoyantCloudClient | null;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,cAAc,EACnB,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,iBAAiB,CAmBnB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,cAAc,EACnB,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,iBAAiB,GAAG,IAAI,CAS1B"}

package/dist/env.js

@@ -0,0 +1,55 @@
+import { createVoyantCloudClient } from "./client.js";
+/**
+ * Thrown when {@link getVoyantCloudClient} cannot construct a client because
+ * `VOYANT_CLOUD_API_KEY` is missing and no override was supplied.
+ */
+export class VoyantCloudConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VoyantCloudConfigError";
+    }
+}
+/**
+ * Construct a {@link VoyantCloudClient} from a runtime bindings object
+ * (Cloudflare Worker `env`, Node `process.env`, etc.).
+ *
+ * `overrides` take precedence over env values, except an empty-string
+ * override is treated as missing so it can't silently clobber a valid env
+ * value.
+ *
+ * Throws {@link VoyantCloudConfigError} when no API key can be resolved
+ * from either source.
+ */
+export function getVoyantCloudClient(env, overrides = {}) {
+    const apiKey = nonEmpty(overrides.apiKey) ?? nonEmpty(env.VOYANT_CLOUD_API_KEY);
+    if (!apiKey) {
+        throw new VoyantCloudConfigError("VOYANT_CLOUD_API_KEY is not set. Set the env variable or pass `apiKey` in overrides.");
+    }
+    const baseUrl = nonEmpty(env.VOYANT_CLOUD_API_URL);
+    const userAgent = nonEmpty(env.VOYANT_CLOUD_USER_AGENT);
+    return createVoyantCloudClient({
+        ...(baseUrl ? { baseUrl } : {}),
+        ...(userAgent ? { userAgent } : {}),
+        ...overrides,
+        apiKey,
+    });
+}
+/**
+ * Like {@link getVoyantCloudClient}, but returns `null` when the API key
+ * is unset instead of throwing. Use from edges that legitimately operate
+ * without cloud (e.g. local dev tooling that doesn't send mail).
+ */
+export function tryGetVoyantCloudClient(env, overrides = {}) {
+    try {
+        return getVoyantCloudClient(env, overrides);
+    }
+    catch (error) {
+        if (error instanceof VoyantCloudConfigError) {
+            return null;
+        }
+        throw error;
+    }
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { createVoyantCloudClient, VoyantCloudClient } from "./client.js";
+export { getVoyantCloudClient, tryGetVoyantCloudClient, VoyantCloudConfigError, } from "./env.js";
+export type { VoyantCloudEnv } from "./env.js";
 export { createSearchClientConfig } from "./search.js";
 export type { SearchClientConfig, SearchClientConfigOptions, } from "./search.js";
 export type { BrowserCommand, BrowserCommandResult, BrowserCookie, BrowserCrawlSummary, BrowserGoToOptions, BrowserJobKind, BrowserJobStatus, BrowserJsonInput, BrowserLink, BrowserPdfInput, BrowserPdfOptions, BrowserRenderInput, BrowserSameSite, BrowserScrapeElement, BrowserScrapeInput, BrowserScrapeResult, BrowserScreenshotInput, BrowserScreenshotOptions, BrowserSessionStatus, BrowserSessionSummary, BrowserSnapshotResult, BrowserViewport, BrowserWaitForSelector, BrowserWaitUntil, CheckVerificationInput, CreateVideoFromUrlInput, CreateVideoUploadInput, CreateVideoWatermarkInput, EmailMessageStatus, EmailMessageSummary, GenerateVideoCaptionInput, MintVideoSignedTokenInput, OpenBrowserSessionInput, PhoneNumberCapabilities, PhoneNumberStatus, PhoneNumberSummary, RunBrowserCommandsInput, RunBrowserCommandsResult, SendEmailAttachment, SendEmailInput, SendSmsInput, SmsMessageStatus, SmsMessageSummary, StartBrowserCrawlInput, StartBrowserCrawlResult, StartVerificationInput, UpdateVideoInput, UploadVideoCaptionInput, VaultSecretSummary, VaultSecretValue, VaultSummary, VerificationAttemptStatus, VerificationAttemptSummary, VerificationChannel, VerificationCheckResult, VideoCaptionStatus, VideoCaptionSummary, VideoDownloadStatus, VideoSignedToken, VideoStatus, VideoSummary, VideoUploadTicket, VideoWatermarkPosition, VideoWatermarkProfileSummary, VoyantCloudClientOptions, } from "./types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EACV,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,yBAAyB,EACzB,0BAA0B,EAC1B,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EACV,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,yBAAyB,EACzB,0BAA0B,EAC1B,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export { createVoyantCloudClient, VoyantCloudClient } from "./client.js";
+export { getVoyantCloudClient, tryGetVoyantCloudClient, VoyantCloudConfigError, } from "./env.js";
 export { createSearchClientConfig } from "./search.js";

package/node_modules/@voyant-sdk/sdk-core/dist/client.js

@@ -70,7 +70,7 @@ export class VoyantTransport {
         this.apiKey = options.apiKey;
         this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
         this.defaultHeaders = options.headers;
-        this.fetchImpl = options.fetch ?? fetch;
+        this.fetchImpl = options.fetch ?? fetch.bind(globalThis);
         this.authHeader = options.authHeader ?? "authorization";
         this.authScheme = options.authScheme === undefined ? "Bearer" : options.authScheme;
         this.userAgent = options.userAgent ?? "voyant-sdk";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/cloud-sdk",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Public TypeScript SDK for Voyant Cloud APIs.",
   "license": "FSL-1.1-Apache-2.0",
   "repository": {