@voyantjs/cloud-sdk 0.4.0 → 0.6.0

package/README.md

@@ -14,6 +14,8 @@ Public TypeScript client for Voyant Cloud APIs.
   long-running crawls and keep-alive Puppeteer sessions)
 - video (manage uploads, playback, captions, watermarks, signed playback
   tokens; create videos from a public URL)
+- search (`createSearchClientConfig` returns a Typesense client config pointed
+  at the Voyant search proxy)
 
 ## Install
 
@@ -34,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:
@@ -44,6 +89,7 @@ Root groups:
 - `email`
 - `browser`
 - `video`
+- `search` (standalone `createSearchClientConfig` export, not on the client)
 
 The `vault` group covers list-vaults, list-secrets, and get-secret routes.
 
@@ -83,6 +129,49 @@ await client.browser.sessions.runCommands(session.id, {
 await client.browser.sessions.close(session.id);
 ```
 
+The `search` surface is a config helper, not a wrapped client. Voyant's
+search proxy speaks the Typesense HTTP protocol, so `createSearchClientConfig`
+hands back a config you pass straight to the official `typesense` package:
+
+```ts
+import { Client } from "typesense";
+import { createSearchClientConfig } from "@voyantjs/cloud-sdk";
+
+const search = new Client(
+  createSearchClientConfig({
+    apiKey: process.env.VOYANT_API_KEY!,
+    organizationSlug: "acme",
+    projectName: "catalog",
+  }),
+);
+
+await search.collections().create({
+  name: "products",
+  fields: [
+    { name: "name", type: "string" },
+    { name: "tags", type: "string[]", facet: true },
+  ],
+});
+
+await search
+  .collections("products")
+  .documents()
+  .import([{ id: "1", name: "Sneakers", tags: ["shoes"] }], {
+    action: "upsert",
+  });
+
+const hits = await search
+  .collections("products")
+  .documents()
+  .search({ q: "sneak", query_by: "name,tags" });
+```
+
+`apiKey` is your Voyant API token (`search:read` for queries,
+`search:write` for writes). The proxy auths with `Authorization: Bearer ...`,
+substitutes the project's scoped Typesense key downstream, and rewrites
+collection names so isolation prefixes never leak into your code. `typesense`
+is a peer requirement — install it alongside the SDK if you use search.
+
 The `video` group covers the Voyant video service: `videos.{list, get,
 createUpload, createFromUrl, update, delete, enableDownload, mintToken}`,
 captions under `videos.captions.{list, upload, generate, delete}`, and
@@ -127,6 +216,7 @@ Useful exported types include:
   `GenerateVideoCaptionInput`, `CreateVideoWatermarkInput`,
   `VideoStatus`, `VideoCaptionStatus`, `VideoDownloadStatus`,
   `VideoWatermarkPosition`
+- `SearchClientConfig`, `SearchClientConfigOptions`
 - `PhoneNumberStatus`, `SmsMessageStatus`, `VerificationChannel`,
   `VerificationAttemptStatus`, `EmailMessageStatus`,
   `BrowserSessionStatus`, `BrowserJobStatus`
@@ -141,7 +231,7 @@ Useful exported types include:
   `verification:read`, `emails:read`, `emails:send`, `browser:render`,
   `browser:scrape`, `browser:extract`, `browser:crawl`, `browser:sessions`,
   `video:read`, `video:upload`, `video:delete`, `video:captions:write`,
-  `video:watermarks:write`);
+  `video:watermarks:write`, `search:read`, `search:write`);
   requests fail with `403` if the token does not include the required scope
 
 For repo-level context, see [../../docs/cloud.md](../../docs/cloud.md).

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,3 +1,7 @@
 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";
 //# 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,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACzE,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 +1,3 @@
 export { createVoyantCloudClient, VoyantCloudClient } from "./client.js";
+export { getVoyantCloudClient, tryGetVoyantCloudClient, VoyantCloudConfigError, } from "./env.js";
+export { createSearchClientConfig } from "./search.js";

package/dist/search.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Configuration helper for the Voyant search surface.
+ *
+ * Voyant's search-api is a thin proxy in front of Typesense. It auths
+ * incoming requests against a Voyant API token, picks the right scoped
+ * Typesense key (read or write) server-side, and rewrites collection
+ * names so customers never see our internal isolation prefix.
+ *
+ * The wire protocol is pure Typesense, so we don't ship a hand-rolled
+ * SDK surface for it. Instead, this helper produces a config object
+ * that you pass directly to the official `typesense` client:
+ *
+ * ```ts
+ * import { Client } from "typesense";
+ * import { createSearchClientConfig } from "@voyantjs/cloud-sdk";
+ *
+ * const search = new Client(createSearchClientConfig({
+ *   apiKey: process.env.VOYANT_API_TOKEN!,
+ *   organizationSlug: "acme",
+ *   projectName: "catalog",
+ * }));
+ *
+ * await search.collections().create({
+ *   name: "products",
+ *   fields: [{ name: "name", type: "string" }],
+ * });
+ * ```
+ *
+ * `apiKey` here is your Voyant API token — it is sent as
+ * `Authorization: Bearer ...`. The proxy strips Typesense's own
+ * `X-TYPESENSE-API-KEY` header from inbound requests and injects the
+ * project's scoped key downstream.
+ */
+export interface SearchClientConfigOptions {
+    /** Voyant API token with `search:read` (queries) or `search:write` (writes) scope. */
+    apiKey: string;
+    /** Organization slug — the first path segment in the search URL. */
+    organizationSlug: string;
+    /** Search project name — the second path segment in the search URL. */
+    projectName: string;
+    /** Override the default `search.voyantjs.com` host (e.g. for local dev). */
+    host?: string;
+    /** Override the default port. */
+    port?: number;
+    /** Override the default `https` protocol. */
+    protocol?: string;
+    /** Additional headers to merge with `Authorization`. */
+    additionalHeaders?: Record<string, string>;
+}
+export interface SearchClientConfig {
+    apiKey: string;
+    nodes: Array<{
+        host: string;
+        port: number;
+        protocol: string;
+        path: string;
+    }>;
+    additionalHeaders: Record<string, string>;
+}
+/**
+ * Build a Typesense client configuration that targets the Voyant
+ * search proxy. Pass the returned object straight to
+ * `new Typesense.Client(...)`.
+ */
+export declare function createSearchClientConfig(options: SearchClientConfigOptions): SearchClientConfig;
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAMH,MAAM,WAAW,yBAAyB;IACxC,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,gBAAgB,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,GACjC,kBAAkB,CA0CpB"}

package/dist/search.js

@@ -0,0 +1,72 @@
+/**
+ * Configuration helper for the Voyant search surface.
+ *
+ * Voyant's search-api is a thin proxy in front of Typesense. It auths
+ * incoming requests against a Voyant API token, picks the right scoped
+ * Typesense key (read or write) server-side, and rewrites collection
+ * names so customers never see our internal isolation prefix.
+ *
+ * The wire protocol is pure Typesense, so we don't ship a hand-rolled
+ * SDK surface for it. Instead, this helper produces a config object
+ * that you pass directly to the official `typesense` client:
+ *
+ * ```ts
+ * import { Client } from "typesense";
+ * import { createSearchClientConfig } from "@voyantjs/cloud-sdk";
+ *
+ * const search = new Client(createSearchClientConfig({
+ *   apiKey: process.env.VOYANT_API_TOKEN!,
+ *   organizationSlug: "acme",
+ *   projectName: "catalog",
+ * }));
+ *
+ * await search.collections().create({
+ *   name: "products",
+ *   fields: [{ name: "name", type: "string" }],
+ * });
+ * ```
+ *
+ * `apiKey` here is your Voyant API token — it is sent as
+ * `Authorization: Bearer ...`. The proxy strips Typesense's own
+ * `X-TYPESENSE-API-KEY` header from inbound requests and injects the
+ * project's scoped key downstream.
+ */
+const DEFAULT_SEARCH_HOST = "search.voyantjs.com";
+const DEFAULT_SEARCH_PORT = 443;
+const DEFAULT_SEARCH_PROTOCOL = "https";
+/**
+ * Build a Typesense client configuration that targets the Voyant
+ * search proxy. Pass the returned object straight to
+ * `new Typesense.Client(...)`.
+ */
+export function createSearchClientConfig(options) {
+    const { apiKey, organizationSlug, projectName, host = DEFAULT_SEARCH_HOST, port = DEFAULT_SEARCH_PORT, protocol = DEFAULT_SEARCH_PROTOCOL, additionalHeaders, } = options;
+    if (!apiKey) {
+        throw new Error("createSearchClientConfig: `apiKey` is required.");
+    }
+    if (!organizationSlug) {
+        throw new Error("createSearchClientConfig: `organizationSlug` is required.");
+    }
+    if (!projectName) {
+        throw new Error("createSearchClientConfig: `projectName` is required.");
+    }
+    return {
+        // typesense-js requires `apiKey`. The proxy strips the
+        // X-TYPESENSE-API-KEY header it adds and uses our bearer token
+        // instead, so this value is ignored downstream — but it must be
+        // a non-empty string for the client to construct.
+        apiKey: "voyant-bearer",
+        nodes: [
+            {
+                host,
+                port,
+                protocol,
+                path: `/${organizationSlug}/${projectName}`,
+            },
+        ],
+        additionalHeaders: {
+            ...additionalHeaders,
+            Authorization: `Bearer ${apiKey}`,
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyantjs/cloud-sdk",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Public TypeScript SDK for Voyant Cloud APIs.",
   "license": "FSL-1.1-Apache-2.0",
   "repository": {
@@ -37,9 +37,18 @@
   "dependencies": {
     "@voyant-sdk/sdk-core": "0.2.0"
   },
+  "peerDependencies": {
+    "typesense": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typesense": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
+    "typesense": "^2.0.0",
     "@voyant-sdk/eslint-config": "0.0.0",
     "@voyant-sdk/typescript-config": "0.0.0"
   },