@infino-ai/infino 0.2.0 → 0.2.1

package/infino/index.d.ts

@@ -18,7 +18,15 @@ export type SchemaDescriptor = Record<string, string | {
 }>;
 /** Accepted shapes for `Table.append`. */
 export type AppendData = RowRecord[] | arrow.Table | arrow.RecordBatch | Buffer | Uint8Array;
-/** Storage and cache config the `connect` URI can't carry. All optional. */
+/**
+ * Storage and cache config the `connect` URI can't carry. All optional.
+ *
+ * Which options apply depends on the backend: `apiKey` is for a hosted
+ * (Infino Cloud) connection, while the storage/cache options — `storageOptions`,
+ * `cacheDir`, `cacheBudgetBytes`, `coldFetchMode`, `validate` — apply to **local
+ * connections only**; Infino Cloud manages storage, so it ignores them.
+ * `connectionMemoryBudgetBytes` applies to both.
+ */
 export interface ConnectOptions {
     /**
      * Credentials/tuning for the URI-selected backend, keyed by `object_store`
@@ -46,6 +54,12 @@ export interface ConnectOptions {
      * on bad credentials instead of on the first table operation.
      */
     validate?: boolean;
+    /**
+     * API key for a hosted (`https://<host>/<database>`) connection, sent as a
+     * bearer credential. Ignored by local backends. Falls back to the
+     * `INFINO_API_KEY` environment variable when omitted.
+     */
+    apiKey?: string;
 }
 /** Row counts returned by `update` / `delete`. */
 export interface MutationStats {
@@ -135,8 +149,10 @@ export interface CountOptions {
 export interface QueryOptions {
     arrow?: boolean;
 }
+/** A table handle. Obtain one from {@link Connection.createTable} or {@link Connection.openTable}. */
 export declare class Table {
     private inner;
+    /** @hidden */
     constructor(inner: any);
     /** The table's Arrow schema. */
     schema(): arrow.Schema;
@@ -187,16 +203,28 @@ export declare class Table {
     /** Delete rows matching a SQL predicate (e.g. `"status = 'spam'"`).
      * Requires durable storage (not `memory://`). */
     delete(predicate: string): MutationStats;
-    /** Merge small / underfilled superfiles into larger ones (omit `settings`
-     * for engine defaults). */
+    /**
+     * Merge small / underfilled superfiles into larger ones (omit `settings`
+     * for engine defaults).
+     *
+     * **Local connections only.** On Infino Cloud, compaction is managed for you,
+     * so calling this on a hosted (`https://…`) connection throws.
+     */
     optimize(settings?: OptimizeOptions): void;
-    /** Delete orphaned storage objects left by compaction or interrupted writes.
+    /**
+     * Delete orphaned storage objects left by compaction or interrupted writes.
      * Only objects older than `graceSecs` (a safety window against racing
-     * readers/writers) are removed. Requires durable storage (not `memory://`). */
+     * readers/writers) are removed. Requires durable storage (not `memory://`).
+     *
+     * **Local connections only.** On Infino Cloud, cleanup is managed for you, so
+     * calling this on a hosted connection throws.
+     */
     gc(graceSecs: number): GcReport;
 }
+/** A catalog connection. Create one with {@link connect}. */
 export declare class Connection {
     private inner;
+    /** @hidden */
     constructor(inner: any);
     /**
      * Provision the database this connection targets. On the hosted service this
@@ -215,5 +243,24 @@ export declare class Connection {
     }): arrow.Table;
     querySql(sql: string, opts?: QueryOptions): RowRecord[];
 }
-/** Open (or create) a catalog rooted at `uri`. */
+/**
+ * Open a connection to Infino. The `uri` selects the backend:
+ *
+ * - a local path (`"./data"`) or `"memory://"` — embedded, in-process;
+ * - an object-store URI (`"s3://…"`, `"gs://…"`, `"az://…"`) — embedded over
+ *   your own bucket;
+ * - `"https://<host>/<database>"` — Infino Cloud, the hosted service.
+ *
+ * For a hosted (`https://`) target, authenticate with an API key: pass
+ * {@link ConnectOptions.apiKey}, or set the `INFINO_API_KEY` environment
+ * variable. Storage and cache tuning the URI can't carry also goes in
+ * `options` (see {@link ConnectOptions}).
+ *
+ * ```ts
+ * // local
+ * const db = connect("./data");
+ * // Infino Cloud
+ * const cloud = connect("https://api.platform.infino.ai/my-app", { apiKey: "inf_…" });
+ * ```
+ */
 export declare function connect(uri: string, options?: ConnectOptions): Connection;

package/infino/index.js

@@ -190,8 +190,10 @@ function decode(buf, asArrow) {
     });
 }
 // --- friendly handles ---
+/** A table handle. Obtain one from {@link Connection.createTable} or {@link Connection.openTable}. */
 class Table {
     inner;
+    /** @hidden */
     constructor(inner) {
         this.inner = inner;
     }
@@ -245,21 +247,33 @@ class Table {
     delete(predicate) {
         return this.inner.delete(predicate);
     }
-    /** Merge small / underfilled superfiles into larger ones (omit `settings`
-     * for engine defaults). */
+    /**
+     * Merge small / underfilled superfiles into larger ones (omit `settings`
+     * for engine defaults).
+     *
+     * **Local connections only.** On Infino Cloud, compaction is managed for you,
+     * so calling this on a hosted (`https://…`) connection throws.
+     */
     optimize(settings) {
         this.inner.optimize(settings);
     }
-    /** Delete orphaned storage objects left by compaction or interrupted writes.
+    /**
+     * Delete orphaned storage objects left by compaction or interrupted writes.
      * Only objects older than `graceSecs` (a safety window against racing
-     * readers/writers) are removed. Requires durable storage (not `memory://`). */
+     * readers/writers) are removed. Requires durable storage (not `memory://`).
+     *
+     * **Local connections only.** On Infino Cloud, cleanup is managed for you, so
+     * calling this on a hosted connection throws.
+     */
     gc(graceSecs) {
         return this.inner.gc(graceSecs);
     }
 }
 exports.Table = Table;
+/** A catalog connection. Create one with {@link connect}. */
 class Connection {
     inner;
+    /** @hidden */
     constructor(inner) {
         this.inner = inner;
     }
@@ -289,7 +303,26 @@ class Connection {
     }
 }
 exports.Connection = Connection;
-/** Open (or create) a catalog rooted at `uri`. */
+/**
+ * Open a connection to Infino. The `uri` selects the backend:
+ *
+ * - a local path (`"./data"`) or `"memory://"` — embedded, in-process;
+ * - an object-store URI (`"s3://…"`, `"gs://…"`, `"az://…"`) — embedded over
+ *   your own bucket;
+ * - `"https://<host>/<database>"` — Infino Cloud, the hosted service.
+ *
+ * For a hosted (`https://`) target, authenticate with an API key: pass
+ * {@link ConnectOptions.apiKey}, or set the `INFINO_API_KEY` environment
+ * variable. Storage and cache tuning the URI can't carry also goes in
+ * `options` (see {@link ConnectOptions}).
+ *
+ * ```ts
+ * // local
+ * const db = connect("./data");
+ * // Infino Cloud
+ * const cloud = connect("https://api.platform.infino.ai/my-app", { apiKey: "inf_…" });
+ * ```
+ */
 function connect(uri, options) {
     return new Connection((0, native_js_1.connect)(uri, options));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infino-ai/infino",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Fast search on object storage — SQL, full-text, and vector search.",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -82,12 +82,12 @@
     "apache-arrow": "^17"
   },
   "optionalDependencies": {
-    "infx-darwin-x64": "0.2.0",
-    "infx-darwin-arm64": "0.2.0",
-    "infx-linux-x64-gnu": "0.2.0",
-    "infx-linux-arm64-gnu": "0.2.0",
-    "infx-linux-x64-musl": "0.2.0",
-    "infx-linux-arm64-musl": "0.2.0"
+    "infx-darwin-x64": "0.2.1",
+    "infx-darwin-arm64": "0.2.1",
+    "infx-linux-x64-gnu": "0.2.1",
+    "infx-linux-arm64-gnu": "0.2.1",
+    "infx-linux-x64-musl": "0.2.1",
+    "infx-linux-arm64-musl": "0.2.1"
   },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.0",