@voyantjs/cloud-sdk 0.4.0 → 0.5.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
 
@@ -44,6 +46,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 +86,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 +173,7 @@ Useful exported types include:
   `GenerateVideoCaptionInput`, `CreateVideoWatermarkInput`,
   `VideoStatus`, `VideoCaptionStatus`, `VideoDownloadStatus`,
   `VideoWatermarkPosition`
+- `SearchClientConfig`, `SearchClientConfigOptions`
 - `PhoneNumberStatus`, `SmsMessageStatus`, `VerificationChannel`,
   `VerificationAttemptStatus`, `EmailMessageStatus`,
   `BrowserSessionStatus`, `BrowserJobStatus`
@@ -141,7 +188,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/index.d.ts

@@ -1,3 +1,5 @@
 export { createVoyantCloudClient, VoyantCloudClient } from "./client.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,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,2 @@
 export { createVoyantCloudClient, VoyantCloudClient } from "./client.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.5.0",
   "description": "Public TypeScript SDK for Voyant Cloud APIs.",
   "license": "FSL-1.1-Apache-2.0",
   "repository": {
@@ -37,11 +37,20 @@
   "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",
-    "@voyant-sdk/eslint-config": "0.0.0",
-    "@voyant-sdk/typescript-config": "0.0.0"
+    "typesense": "^2.0.0",
+    "@voyant-sdk/typescript-config": "0.0.0",
+    "@voyant-sdk/eslint-config": "0.0.0"
   },
   "publishConfig": {
     "access": "public"