@findlane/server 0.23.0 → 0.24.0

package/dist/index.cjs

@@ -291,6 +291,17 @@ class SearchServerClient {
         uploadFromUrl: (url, signal) => request("/images", "POST", { url }, signal),
         delete: (key, signal) => request(`/images/${key}`, "DELETE", undefined, signal)
       },
+      feed: {
+        get: async (signal) => (await request("/feed", "GET", undefined, signal)).feed,
+        set: async (setup, signal) => (await request("/feed", "PUT", setup, signal)).feed,
+        remove: async (signal) => {
+          await request("/feed", "DELETE", undefined, signal);
+        },
+        check: (setup = {}, signal) => request("/feed/check", "POST", setup, signal),
+        run: async (signal) => (await request("/feed/runs", "POST", undefined, signal)).run,
+        runs: async (signal) => (await request("/feed/runs", "GET", undefined, signal)).runs,
+        importHeld: async (runId, signal) => (await request(`/feed/runs/${encodeURIComponent(runId)}/import`, "POST", undefined, signal)).run
+      },
       lists: {
         get: (id, options = {}) => request(`/lists/${encodeURIComponent(id)}${options.limit ? `?limit=${options.limit}` : ""}`, "GET", undefined, options.signal),
         getMany: async (ids, options = {}) => {

package/dist/index.d.cts

@@ -832,6 +832,71 @@ export type BannerStatsReport = {
     }[];
     analytics: "ok" | "off" | "unavailable";
 };
+export type FeedFormat = "xml" | "tsv" | "csv" | "json" | "jsonl";
+/** One run of a product feed: unchanged when the file hadn't changed; held when it would have emptied the index,
+ * removed more than half its products, or refused a fifth of its items (`message` says which). */
+export type FeedRun = {
+    id: string;
+    trigger: "schedule" | "manual" | "connect" | "held";
+    status: "running" | "unchanged" | "imported" | "held" | "failed";
+    startedAt: string;
+    finishedAt: string | null;
+    format: FeedFormat | null;
+    bytes: number | null;
+    items: number | null;
+    records: number | null;
+    added: number | null;
+    changed: number | null;
+    removed: number | null;
+    refused: number | null;
+    reasons: Record<string, number>;
+    refusals: {
+        id?: string;
+        reason: string;
+    }[];
+    message: string | null;
+};
+/** An index's product feed: where it's read from, when, and how its last run went. `password` says whether it has one. */
+export type ProductFeed = {
+    url: string;
+    username: string | null;
+    password: boolean;
+    schedule: "hourly" | "6h" | "daily";
+    hour: number | null;
+    variants: "group" | "separate";
+    paused: boolean;
+    pausedReason: "owner" | "failing" | null;
+    failures: number;
+    running: boolean;
+    nextRunAt: string | null;
+    lastRun: FeedRun | null;
+    held: FeedRun | null;
+};
+/** A feed's setup: each field given replaces the current one; null clears the username or password. */
+export type FeedSetup = {
+    url?: string;
+    username?: string | null;
+    password?: string | null;
+    schedule?: "hourly" | "6h" | "daily";
+    hour?: number;
+    variants?: "group" | "separate";
+    paused?: boolean;
+};
+/** What a feed's first 2,000 items hold: the records they make (the first five in `sample`), and refused items. */
+export type FeedCheck = {
+    format: FeedFormat | null;
+    complete: boolean;
+    items: number;
+    records: number;
+    refused: number;
+    sample: Record<string, unknown>[];
+    fields: string[];
+    reasons: Record<string, number>;
+    refusals: {
+        id?: string;
+        reason: string;
+    }[];
+};
 /** A past order for importOrders; `timestamp` is when it was placed (ms, a Date, or an ISO string). */
 export type Order = {
     orderID: string;
@@ -1158,6 +1223,25 @@ export declare class SearchServerClient {
                 deleted: true;
             }>;
         };
+        /** The index's product feed (0.24.0): a store's Google or Meta product feed, or a JSON file of records, read on
+         * a schedule (hourly, every 6 hours, or daily), replacing the index's records with only what changed. Reading
+         * needs the `search` or `write` scope; the rest, `write`. */
+        feed: {
+            /** The feed and its last run, or null. */
+            get: (signal?: AbortSignal) => Promise<ProductFeed | null>;
+            /** Connects a feed or changes its setup; a new address, sign-in or variants setting reads it now. */
+            set: (setup: FeedSetup, signal?: AbortSignal) => Promise<ProductFeed>;
+            /** Disconnects it; the index keeps its records. */
+            remove: (signal?: AbortSignal) => Promise<void>;
+            /** Reads a feed's first 2,000 items without saving anything; without a url, the connected feed's. */
+            check: (setup?: Pick<FeedSetup, "url" | "username" | "password" | "variants">, signal?: AbortSignal) => Promise<FeedCheck>;
+            /** Reads it now, in full, in the background; `runs` shows how it went. */
+            run: (signal?: AbortSignal) => Promise<FeedRun>;
+            /** The last 20 runs, newest first. */
+            runs: (signal?: AbortSignal) => Promise<FeedRun[]>;
+            /** Imports a held run's copy of the feed as it is, without the checks that held it. */
+            importHeld: (runId: string, signal?: AbortSignal) => Promise<FeedRun>;
+        };
         lists: {
             /** One list by its ID; throws a FindlaneError with status 404 when there's none. `limit` shows fewer. */
             get: <R = T>(id: string, options?: {

package/dist/index.d.ts

@@ -832,6 +832,71 @@ export type BannerStatsReport = {
     }[];
     analytics: "ok" | "off" | "unavailable";
 };
+export type FeedFormat = "xml" | "tsv" | "csv" | "json" | "jsonl";
+/** One run of a product feed: unchanged when the file hadn't changed; held when it would have emptied the index,
+ * removed more than half its products, or refused a fifth of its items (`message` says which). */
+export type FeedRun = {
+    id: string;
+    trigger: "schedule" | "manual" | "connect" | "held";
+    status: "running" | "unchanged" | "imported" | "held" | "failed";
+    startedAt: string;
+    finishedAt: string | null;
+    format: FeedFormat | null;
+    bytes: number | null;
+    items: number | null;
+    records: number | null;
+    added: number | null;
+    changed: number | null;
+    removed: number | null;
+    refused: number | null;
+    reasons: Record<string, number>;
+    refusals: {
+        id?: string;
+        reason: string;
+    }[];
+    message: string | null;
+};
+/** An index's product feed: where it's read from, when, and how its last run went. `password` says whether it has one. */
+export type ProductFeed = {
+    url: string;
+    username: string | null;
+    password: boolean;
+    schedule: "hourly" | "6h" | "daily";
+    hour: number | null;
+    variants: "group" | "separate";
+    paused: boolean;
+    pausedReason: "owner" | "failing" | null;
+    failures: number;
+    running: boolean;
+    nextRunAt: string | null;
+    lastRun: FeedRun | null;
+    held: FeedRun | null;
+};
+/** A feed's setup: each field given replaces the current one; null clears the username or password. */
+export type FeedSetup = {
+    url?: string;
+    username?: string | null;
+    password?: string | null;
+    schedule?: "hourly" | "6h" | "daily";
+    hour?: number;
+    variants?: "group" | "separate";
+    paused?: boolean;
+};
+/** What a feed's first 2,000 items hold: the records they make (the first five in `sample`), and refused items. */
+export type FeedCheck = {
+    format: FeedFormat | null;
+    complete: boolean;
+    items: number;
+    records: number;
+    refused: number;
+    sample: Record<string, unknown>[];
+    fields: string[];
+    reasons: Record<string, number>;
+    refusals: {
+        id?: string;
+        reason: string;
+    }[];
+};
 /** A past order for importOrders; `timestamp` is when it was placed (ms, a Date, or an ISO string). */
 export type Order = {
     orderID: string;
@@ -1158,6 +1223,25 @@ export declare class SearchServerClient {
                 deleted: true;
             }>;
         };
+        /** The index's product feed (0.24.0): a store's Google or Meta product feed, or a JSON file of records, read on
+         * a schedule (hourly, every 6 hours, or daily), replacing the index's records with only what changed. Reading
+         * needs the `search` or `write` scope; the rest, `write`. */
+        feed: {
+            /** The feed and its last run, or null. */
+            get: (signal?: AbortSignal) => Promise<ProductFeed | null>;
+            /** Connects a feed or changes its setup; a new address, sign-in or variants setting reads it now. */
+            set: (setup: FeedSetup, signal?: AbortSignal) => Promise<ProductFeed>;
+            /** Disconnects it; the index keeps its records. */
+            remove: (signal?: AbortSignal) => Promise<void>;
+            /** Reads a feed's first 2,000 items without saving anything; without a url, the connected feed's. */
+            check: (setup?: Pick<FeedSetup, "url" | "username" | "password" | "variants">, signal?: AbortSignal) => Promise<FeedCheck>;
+            /** Reads it now, in full, in the background; `runs` shows how it went. */
+            run: (signal?: AbortSignal) => Promise<FeedRun>;
+            /** The last 20 runs, newest first. */
+            runs: (signal?: AbortSignal) => Promise<FeedRun[]>;
+            /** Imports a held run's copy of the feed as it is, without the checks that held it. */
+            importHeld: (runId: string, signal?: AbortSignal) => Promise<FeedRun>;
+        };
         lists: {
             /** One list by its ID; throws a FindlaneError with status 404 when there's none. `limit` shows fewer. */
             get: <R = T>(id: string, options?: {

package/dist/index.js

@@ -245,6 +245,17 @@ class SearchServerClient {
         uploadFromUrl: (url, signal) => request("/images", "POST", { url }, signal),
         delete: (key, signal) => request(`/images/${key}`, "DELETE", undefined, signal)
       },
+      feed: {
+        get: async (signal) => (await request("/feed", "GET", undefined, signal)).feed,
+        set: async (setup, signal) => (await request("/feed", "PUT", setup, signal)).feed,
+        remove: async (signal) => {
+          await request("/feed", "DELETE", undefined, signal);
+        },
+        check: (setup = {}, signal) => request("/feed/check", "POST", setup, signal),
+        run: async (signal) => (await request("/feed/runs", "POST", undefined, signal)).run,
+        runs: async (signal) => (await request("/feed/runs", "GET", undefined, signal)).runs,
+        importHeld: async (runId, signal) => (await request(`/feed/runs/${encodeURIComponent(runId)}/import`, "POST", undefined, signal)).run
+      },
       lists: {
         get: (id, options = {}) => request(`/lists/${encodeURIComponent(id)}${options.limit ? `?limit=${options.limit}` : ""}`, "GET", undefined, options.signal),
         getMany: async (ids, options = {}) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findlane/server",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Findlane server SDK: upload catalogs, manage index settings, and search with a secret workspace API key.",
   "keywords": ["findlane", "search", "full-text search", "typo tolerance", "ecommerce search", "search api", "sdk"],
   "license": "MIT",