@rushdb/javascript-sdk 2.11.0 → 3.0.0

package/README.md

@@ -172,14 +172,67 @@ const relationships = await db.relationships.find({
 
 ---
 
+## RushDB Cloud or a self-hosted engine
+
+The SDK works with RushDB in one of two ways:
+
+| | RushDB Cloud | Self-hosted RushDB engine (direct mode) |
+| --- | --- | --- |
+| What you run | nothing: the managed service at [app.rushdb.com](https://app.rushdb.com) | one `rushdbd` binary, on your own infrastructure |
+| Connect with | an API key | the engine URL and the engine token |
+
+The engine is what you can self-host. RushDB Cloud runs that engine for you and adds the dashboard,
+managed embeddings and the AI features (natural-language search, relationship-pattern suggestions),
+which exist only in RushDB Cloud.
+
+```typescript
+// RushDB Cloud
+const db = new RushDB('RUSHDB_API_KEY')
+
+// A self-hosted engine
+const db = new RushDB('ENGINE_TOKEN', {
+  direct: true,
+  engineUrl: 'http://127.0.0.1:3000',
+  scope: 'tenant-1' // only for an engine started with --multitenant
+})
+```
+
+What each offers:
+
+| Feature | Cloud | Self-hosted engine |
+| --- | :---: | :---: |
+| Records: create, read, update, set, upsert, delete, `find` with `where`, `orderBy`, `select`, `groupBy` | ✓ | ✓ |
+| Relationships: `attach`/`detach`, `relationships.createMany`/`deleteMany`/`find` | ✓ | ✓ |
+| Labels, properties, property values | ✓ | ✓ |
+| Import JSON and CSV, export CSV | ✓ | ✓ |
+| Text indexes and keyword search (`records.textSearch`) | ✓ | ✓ |
+| External vector indexes; vector and hybrid search with a `queryVector` you supply | ✓ | ✓ |
+| Raw openCypher (`query.raw`; the engine needs `--languages cypher`) | ✓ | ✓ |
+| Schema (`ai.getSchema`, `ai.getSchemaMarkdown`) | ✓ | ✓ |
+| Transactions | ✓ | record creates, updates, sets, deletes by id, attaches and imports are staged; other writes refuse a transaction |
+| Managed embeddings: managed indexes, `records.vectorSearch` by text `query` | ✓ | — |
+| Natural-language search (`ai.search`) | ✓ | — |
+| Relationship-pattern suggestions (`relationships.patterns.*`) | ✓ | — |
+| Project settings (`settings.get`), dashboard, projects, team access, MCP over HTTP with OAuth | ✓ | — |
+
+In direct mode a Cloud-only method throws `CloudOnlyError` (with `method` and `reason`) before
+sending anything, and no request ever goes to RushDB Cloud. A write the engine cannot stage into a
+transaction throws `DirectModeError`, also before sending anything. The list is available in code:
+
+```typescript
+import { CLOUD_ONLY_METHODS, CloudOnlyError, isCloudOnlyMethod } from '@rushdb/javascript-sdk'
+```
+
+---
+
 ## SDK configuration
 
 ```typescript
 import RushDB from '@rushdb/javascript-sdk'
 
 const db = new RushDB('RUSHDB_API_KEY', {
-  // Override for self-hosted or staging
-  url: 'http://your-rushdb-server.com/api/v1',
+  // A different RushDB Cloud API endpoint (default: https://api.rushdb.com/api/v1)
+  url: 'https://api.rushdb.com/api/v1',
   timeout: 30000
 })
 ```
@@ -191,6 +244,7 @@ Key options:
 - `timeout` — request timeout in ms (default: 10000)
 - `httpClient` — custom HTTP client for advanced use
 - `options.allowForceDelete` — allow deleting all records without criteria (default: false)
+- `direct`, `engineUrl`, `scope` — direct mode against a standalone engine (see above)
 
 Full config reference: [docs.rushdb.com/typescript-sdk/introduction#sdk-configuration-options](https://docs.rushdb.com/typescript-sdk/introduction#sdk-configuration-options)
 

package/dist/api/api.d.ts

@@ -1,16 +1,23 @@
 import type { HttpClient } from '../network/HttpClient.js';
+import { DirectEngine } from '../direct/engine.js';
 import type { DBRecordCreationOptions, DBRecordTarget, Relation, RelationDetachOptions, RelationDirection, RelationOptions, RelationTarget } from '../sdk/record.js';
 import { DBRecordInstance, DBRecordsArrayInstance } from '../sdk/record.js';
 import type { SDKConfig } from '../sdk/types.js';
 import type { FlatObject, InferSchemaTypesWrite, MaybeArray, OrderDirection, Property, PropertyDraft, PropertyValuesData, Schema, RelationshipSearchQuery, SearchQuery, Where } from '../types/index.js';
 import type { ApiResponse } from './types.js';
-import type { CreateEmbeddingIndexParams, DeleteRelationshipPatternOptions, EmbeddingIndex, EmbeddingIndexStats, RelationshipPatternListResponse, SmartSearchOptions, UpsertEmbeddingVectorsParams, UpsertEmbeddingVectorsResult, VectorEntry, VectorSearchParams } from './types.js';
+import type { CreateEmbeddingIndexParams, DeleteRelationshipPatternOptions, EmbeddingIndex, EmbeddingIndexStats, RelationshipPatternListResponse, SmartSearchOptions, UpsertEmbeddingVectorsParams, UpsertEmbeddingVectorsResult, CreateTextIndexParams, TextIndex, TextSearchParams, VectorEntry, VectorSearchParams } from './types.js';
 import { createFetcher } from '../network/index.js';
 import { Transaction } from '../sdk/transaction.js';
 export declare class RestAPI {
     fetcher: ReturnType<typeof createFetcher>;
     options: SDKConfig['options'];
     logger: SDKConfig['logger'];
+    /**
+     * Direct engine transport (standalone `rushdbd`) when `direct` mode is set.
+     * In direct mode every request is answered from the engine; nothing is sent
+     * to RushDB Cloud.
+     */
+    direct: DirectEngine | undefined;
     constructor(token?: string, config?: SDKConfig & {
         httpClient: HttpClient;
     });
@@ -61,6 +68,8 @@ export declare class RestAPI {
          * @param transaction - Optional transaction for atomic operations
          * @returns Promise resolving to the created DBRecordInstance
          * @throws Error if data is not a flat object and createMany should be used instead
+         * @remarks In direct mode a record created inside a transaction is staged into it, with an id
+         * generated by the SDK. An upsert or inline vectors inside a transaction throw `DirectModeError`.
          */
         create: <S extends Schema = any>({ label, data: rawData, options, vectors }: {
             label: string;
@@ -188,9 +197,20 @@ export declare class RestAPI {
          * RushDB narrows candidates by `labels` and optional `where` filters first, then ranks them by
          * similarity. Pass either `query` for managed indexes or `queryVector` for external/custom vectors.
          *
+         * @remarks In direct mode (a standalone engine) only `queryVector` works: a text `query` is embedded
+         * with RushDB Cloud's managed model, so it throws `CloudOnlyError` without sending a request.
+         *
          * @param params - Vector search parameters including the indexed property, labels, and query input
          */
         vectorSearch: <S extends Schema = any>(params: VectorSearchParams, transaction?: Transaction | string) => Promise<DBRecordsArrayInstance<S>>;
+        /**
+         * Keyword (BM25) search over a text index: the records matching `query`,
+         * best first (`__score`), among those `labels` and `where` select.
+         * `total` counts every match, not just the page.
+         *
+         * @param params - Keywords, the index (or the label whose one text index to use) and filters
+         */
+        textSearch: <S extends Schema = any>(params: TextSearchParams, transaction?: Transaction | string) => Promise<DBRecordsArrayInstance<S>>;
         /**
          * Retrieves record(s) by ID
          * @param idOrIds - Single ID or array of IDs to retrieve
@@ -278,25 +298,30 @@ export declare class RestAPI {
         patterns: {
             /**
              * Lists inferred relationship patterns, schema relationships, and analysis status.
+             * @remarks **RushDB Cloud only.** In direct mode this throws `CloudOnlyError` without sending a request.
              */
             list: () => Promise<ApiResponse<RelationshipPatternListResponse>>;
             /**
              * Queues schema analysis to generate relationship pattern suggestions.
+             * @remarks **RushDB Cloud only.** In direct mode this throws `CloudOnlyError` without sending a request.
              */
             analyze: () => Promise<ApiResponse<{
                 queued: true;
             }>>;
             /**
              * Approves and applies a suggested relationship pattern.
+             * @remarks **RushDB Cloud only.** In direct mode this throws `CloudOnlyError` without sending a request.
              */
             approve: (id: string) => Promise<ApiResponse<import("./types.js").RelationshipPatternDto | undefined>>;
             /**
              * Ignores a suggested relationship pattern without applying it.
+             * @remarks **RushDB Cloud only.** In direct mode this throws `CloudOnlyError` without sending a request.
              */
             ignore: (id: string) => Promise<ApiResponse<import("./types.js").RelationshipPatternDto | undefined>>;
             /**
              * Deletes a saved relationship pattern.
              * Pass deleteExisting to also remove relationships materialized by the pattern.
+             * @remarks **RushDB Cloud only.** In direct mode this throws `CloudOnlyError` without sending a request.
              */
             delete: (id: string, options?: DeleteRelationshipPatternOptions) => Promise<ApiResponse<{
                 deleted: true;
@@ -425,6 +450,7 @@ export declare class RestAPI {
          */
         begin: (config?: Partial<{
             ttl: number;
+            autocommit: boolean;
         }>) => Promise<Transaction>;
         /**
          * Commits a transaction, making its changes permanent
@@ -453,19 +479,19 @@ export declare class RestAPI {
         }>>;
     };
     settings: {
+        /**
+         * The project's settings.
+         * @remarks **RushDB Cloud only.** In direct mode this throws `CloudOnlyError` without sending a request.
+         */
         get: () => Promise<ApiResponse<{
             selfHosted: boolean;
-            customDB?: boolean;
-            managedDB?: boolean;
         } | undefined>>;
     };
     query: {
         /**
-         * Executes a raw query against the underlying database engine.
-         *
-         * NOTE: This endpoint is cloud-only — available only on the RushDB managed
-         * service or when your project is connected to a custom database through
-         * RushDB Cloud. It will not work for self-hosted or local-only deployments.
+         * Executes an openCypher statement against the project's data and
+         * returns `{ records }`, one object per row. The engine must run with the
+         * `cypher` language enabled (the bundled deploy templates enable it).
          *
          * @param param0 - Object containing the query and optional params
          * @param param0.query - Query string to execute
@@ -481,6 +507,28 @@ export declare class RestAPI {
     /**
      * API methods for AI-assisted graph exploration.
      */
+    /**
+     * BM25 text indexes, searched with `db.records.textSearch()` or as the
+     * keyword leg of a hybrid `db.records.vectorSearch({ text })`.
+     */
+    textIndexes: {
+        /** Lists the project's text indexes. */
+        find: () => Promise<ApiResponse<TextIndex[]>>;
+        /**
+         * Declares a text index over one property of a label, or every string of
+         * it (`property: '*'`). It is built online; its `status` turns `ready`.
+         */
+        create: (params: CreateTextIndexParams) => Promise<ApiResponse<TextIndex>>;
+        /** The name a new text index would get by default, unique in the project. */
+        suggestName: (params: Pick<CreateTextIndexParams, "label" | "property">) => Promise<ApiResponse<{
+            name: string;
+        }>>;
+        /** Drops a text index by name. */
+        delete: (name: string) => Promise<ApiResponse<{
+            deleted: boolean;
+        }>>;
+    };
+    private textIndexRequest;
     ai: {
         /**
          * Returns the full graph schema as structured JSON.
@@ -488,8 +536,8 @@ export declare class RestAPI {
          * and cross-label relationships with direction.
          * Properties may include a `vectorIndexes` array when one or more embedding indexes
          * exist for that property — a non-empty array means the property is queryable with
-         * `db.records.vectorSearch()`. Each entry exposes: id, sourceType, similarityFunction, dimensions,
-         * status, and modelKey.
+         * `db.records.vectorSearch()`. Each entry exposes: id, name, sourceType, similarityFunction,
+         * dimensions, status, and modelKey.
          * Use property `id` fields to pass to db.properties.values() for deeper drill-down.
          * @param params - Optional filter. `labels` scopes to specific labels only.
          *                 `force: true` bypasses the 1-hour schema cache and triggers a full recalculation.
@@ -524,9 +572,12 @@ export declare class RestAPI {
             find: () => Promise<ApiResponse<EmbeddingIndex[]>>;
             /**
              * Creates a new embedding index policy for a string property.
+             * @param params.name - Index name, unique within the project (defaults to
+             *   `<label>.<property>.<model>.<dimensions>.<similarity>`)
              * @param params.propertyName - Name of the property to index
-             * @param params.modelKey - Embedding model identifier (e.g. 'text-embedding-3-small')
              * @param params.dimensions - Vector dimensionality produced by the model
+             * @remarks In direct mode (a standalone engine) only external indexes (`external: true`) can be
+             * created; a managed index is filled by RushDB Cloud's embedding model, so it throws `CloudOnlyError`.
              */
             create: (params: CreateEmbeddingIndexParams) => Promise<ApiResponse<EmbeddingIndex>>;
             /**
@@ -543,7 +594,7 @@ export declare class RestAPI {
                 deleted: boolean;
             }>>;
             /**
-             * Returns Neo4j-level statistics for an embedding index.
+             * Returns indexing statistics for an embedding index.
              * @param id - The ID of the embedding index
              */
             stats: (id: string) => Promise<ApiResponse<EmbeddingIndexStats>>;
@@ -556,6 +607,8 @@ export declare class RestAPI {
          *
          * Use `db.records.vectorSearch({ ... })` for direct vector similarity over embedding indexes.
          *
+         * @remarks **RushDB Cloud only.** In direct mode this throws `CloudOnlyError` without sending a request.
+         *
          * @param prompt - Natural-language search request to convert into a SearchQuery and execute
          * @param options - Optional smart-search context and transaction
          */

package/dist/api/index.d.ts

@@ -1,2 +1,2 @@
 export { RestAPI } from './api.js';
-export { ApiResponse, CreateEmbeddingIndexParams, DeleteRelationshipPatternOptions, EmbeddingIndex, EmbeddingIndexStats, RelationshipPattern, RelationshipPatternDirection, RelationshipPatternDto, RelationshipPatternEndpoint, RelationshipPatternListResponse, RelationshipPatternMode, RelationshipPatternOrigin, RelationshipPatternStatus, SemanticSearchParams, SemanticSearchResult, SmartSearchOptions, SmartSearchQueryResponse, UpsertEmbeddingVectorItem, UpsertEmbeddingVectorsParams, UpsertEmbeddingVectorsResult, VectorSearchParams, VectorSearchResult } from './types.js';
+export { ApiResponse, CreateEmbeddingIndexParams, CreateTextIndexParams, DeleteRelationshipPatternOptions, EmbeddingIndex, EmbeddingIndexStats, RelationshipPattern, RelationshipPatternDirection, RelationshipPatternDto, RelationshipPatternEndpoint, RelationshipPatternListResponse, RelationshipPatternMode, RelationshipPatternOrigin, RelationshipPatternStatus, SemanticSearchParams, SemanticSearchResult, SmartSearchOptions, SmartSearchQueryResponse, TextIndex, TextSearchParams, TextSearchReport, UpsertEmbeddingVectorItem, UpsertEmbeddingVectorsParams, UpsertEmbeddingVectorsResult, VectorSearchParams, VectorSearchReport, VectorSearchResult } from './types.js';

package/dist/api/types.d.ts

@@ -8,8 +8,14 @@ export type ApiResponse<T, E = Record<string, any>> = {
 /** An embedding index policy stored in RushDB. */
 export type EmbeddingIndex = {
     id: string;
+    /**
+     * Public index name, unique within the project, e.g.
+     * `Book.description.text-embedding-3-small.1536.cosine`. Search and inline
+     * vectors may address the index by it.
+     */
+    name: string;
     projectId: string;
-    /** Neo4j label this index is scoped to (e.g. "Book"). */
+    /** Record label this index is scoped to (e.g. "Book"). */
     label: string;
     propertyName: string;
     modelKey: string;
@@ -25,7 +31,13 @@ export type EmbeddingIndex = {
 };
 /** Parameters for creating a new embedding index. */
 export type CreateEmbeddingIndexParams = {
-    /** Neo4j label to scope this index to (e.g. "Book", "Task"). */
+    /**
+     * Index name, unique within the project: 1–64 characters of letters,
+     * digits, `.`, `_`, `:` or `-`. Defaults to
+     * `<label>.<property>.<model>.<dimensions>.<similarity>`.
+     */
+    name?: string;
+    /** Record label to scope this index to (e.g. "Book", "Task"). */
     label: string;
     propertyName: string;
     sourceType?: 'managed' | 'external';
@@ -51,6 +63,8 @@ export type VectorEntry = {
      * `similarityFunction`. Omit when there is only one matching index.
      */
     similarityFunction?: 'cosine' | 'euclidean';
+    /** The index to write to, by name (or id). Overrides selection by shape. */
+    index?: string;
 };
 export type UpsertEmbeddingVectorItem = {
     recordId: string;
@@ -63,25 +77,30 @@ export type UpsertEmbeddingVectorsResult = {
     updated: number;
     requested: number;
 };
-/** Neo4j-level stats for an embedding index. */
+/** Indexing statistics for an embedding index. */
 export type EmbeddingIndexStats = {
     totalRecords: number;
     indexedRecords: number;
 };
 /** Parameters for vector search over an embedding index. */
 export type VectorSearchParams = {
-    /** Name of the indexed property to search against. */
-    propertyName: string;
+    /**
+     * The index to search, by name (or id). When given, `propertyName` and
+     * `labels` default to the index's own.
+     */
+    index?: string;
+    /** Name of the indexed property to search against. Required unless `index` is given. */
+    propertyName?: string;
     /** Free-text query that will be embedded and compared against indexed vectors. */
     query?: string;
     /** External vector query. Use instead of query text for external indexes. */
     queryVector?: number[];
     /**
-     * One or more Neo4j labels to scope the search.
+     * One or more record labels to scope the search.
      * The first label is used to resolve which embedding index to use.
-     * Required — always provide at least one label.
+     * Required unless `index` is given.
      */
-    labels: string[];
+    labels?: string[];
     sourceType?: 'managed' | 'external';
     similarityFunction?: 'cosine' | 'euclidean';
     dimensions?: number;
@@ -92,10 +111,92 @@ export type VectorSearchParams = {
     where?: Record<string, unknown>;
     /** Number of results to skip for pagination (default 0). */
     skip?: number;
-    /** Max candidates to fetch from the vector index in direct vector-index mode. */
-    topK?: number;
+    /**
+     * How the search ranks candidates. `auto` (default): the engine scores every
+     * vector of a small index exactly and uses its ANN graph on a large one.
+     * `exact` / `ann` force a path (`ann` needs a cosine index).
+     */
+    mode?: 'auto' | 'exact' | 'ann';
+    /** ANN gather breadth when the search runs on the ANN graph. */
+    ef?: number;
+    /**
+     * Keep only results scoring at least this much. Scores depend on the
+     * embedding model, so pick the threshold per model; a page may then hold
+     * fewer than `limit` results.
+     */
+    scoreThreshold?: number;
     /** Maximum number of results to return (default 20). */
     limit?: number;
+    /**
+     * Adds a BM25 keyword leg, making it a hybrid search: the engine ranks both
+     * legs among the same filtered records and fuses the two rankings. `query`
+     * defaults to the semantic `query`; the text index defaults to the one ready
+     * text index of the first label.
+     */
+    text?: Partial<Pick<TextSearchParams, 'query' | 'index' | 'property' | 'allTerms' | 'phrase'>> & {
+        /** This leg's share of the fused score (≥ 0, default 1). */
+        weight?: number;
+        /** Hits this leg ranks before fusion (1–10,000; default 4 × (skip + limit)). */
+        prefetchLimit?: number;
+    };
+    /** Hybrid only: the vector leg's share of the fused score (≥ 0, default 1). */
+    weight?: number;
+    /** Hybrid only: hits the vector leg ranks before fusion (1–10,000). */
+    prefetchLimit?: number;
+    /**
+     * Hybrid only: how the legs combine. `rrf` (default) fuses ranks; `dbsf`
+     * fuses each leg's scores normalized by its own distribution (mean ± 3σ).
+     */
+    fusion?: 'rrf' | 'dbsf';
+    /** Hybrid only: the RRF smoothing constant (default 60). */
+    rrfK?: number;
+};
+/** A BM25 text index. */
+export type TextIndex = {
+    /** Index name, unique within the project. */
+    name: string;
+    label: string;
+    /** The indexed property, or `*` for every string of the record. */
+    property: string;
+    /** `eventual` (searches see changes shortly after they commit) or `immediate`. */
+    consistency: 'eventual' | 'immediate';
+    status: 'building' | 'ready' | 'dropping';
+    /** Changes the index has not applied yet. */
+    pending: number;
+};
+export type CreateTextIndexParams = {
+    label: string;
+    /** A property name, or `*` for every string of the record. */
+    property: string;
+    /** Defaults to `<label>.<property>.text` (`all` for `*`), unique within the project. */
+    name?: string;
+    consistency?: 'eventual' | 'immediate';
+};
+/** Parameters for keyword (BM25) search. */
+export type TextSearchParams = {
+    /** Keywords; `"a phrase"`, `-excluded` and `+required` follow the query syntax. */
+    query: string;
+    /** The text index, by name; otherwise the one ready text index of the first label. */
+    index?: string;
+    /** Narrows the choice of text index to one over this property. */
+    property?: string;
+    labels?: string[];
+    /** Filter applied before ranking. */
+    where?: Record<string, unknown>;
+    skip?: number;
+    /** Maximum number of results (default 10). */
+    limit?: number;
+    /** Every keyword must match (AND) instead of any (OR). */
+    allTerms?: boolean;
+    /** Match the keywords as one phrase. */
+    phrase?: boolean;
+};
+/** How the engine ran a keyword search, or the keyword leg of a hybrid one. */
+export type TextSearchReport = {
+    /** Records matching the keywords among the filtered records. */
+    matches: number;
+    /** Changes the index had not applied when the search ran. */
+    pending: number;
 };
 /**
  * A record returned by db.records.vectorSearch().
@@ -107,6 +208,21 @@ export type VectorSearchParams = {
 export type VectorSearchResult<S extends Schema = Schema> = DBRecord<S> & {
     readonly __score: number;
 };
+/** How the engine ran a vector search. */
+export type VectorSearchReport = {
+    /** The path that produced the results. */
+    mode: 'exact' | 'ann';
+    /** Gather breadth, for an ANN search. */
+    ef?: number;
+    /**
+     * Why a search that would use the ANN graph was answered exactly:
+     * `metric`, `budget`, `lowConfidence`, or `annWarming` (the graph is being
+     * built; later searches use it).
+     */
+    fallback?: 'metric' | 'budget' | 'lowConfidence' | 'annWarming';
+    /** Vectors in the index. */
+    pool: number;
+};
 /** @deprecated Use VectorSearchParams. */
 export type SemanticSearchParams = VectorSearchParams;
 /** @deprecated Use VectorSearchResult. */

package/dist/direct/capabilities.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What RushDB Cloud adds over a standalone engine, as SDK methods. One list:
+ * the direct-mode router refuses these with `CloudOnlyError`, the MCP server
+ * hides the tools built on them, and the docs mark them.
+ *
+ * Everything else the SDK offers runs against a standalone `rushdbd` too.
+ */
+export declare const CLOUD_ONLY_METHODS: {
+    readonly 'ai.search': "natural-language search turns the prompt into a query with an LLM";
+    readonly 'relationships.patterns.list': "relationship-pattern suggestions are produced and stored by the platform";
+    readonly 'relationships.patterns.analyze': "relationship-pattern suggestions are produced and stored by the platform";
+    readonly 'relationships.patterns.approve': "relationship-pattern suggestions are produced and stored by the platform";
+    readonly 'relationships.patterns.ignore': "relationship-pattern suggestions are produced and stored by the platform";
+    readonly 'relationships.patterns.delete': "relationship-pattern suggestions are produced and stored by the platform";
+    readonly 'settings.get': "project settings belong to the platform";
+};
+/**
+ * Methods available in direct mode in one form only; the other form needs
+ * RushDB Cloud.
+ */
+export declare const CLOUD_ONLY_FORMS: {
+    readonly 'records.vectorSearch': "a text `query` is embedded with the managed embedding model; in direct mode pass `queryVector`";
+    readonly 'ai.indexes.create': "a managed index is filled by the managed embedding model; in direct mode create an external index (`external: true`) and supply vectors";
+};
+export type CloudOnlyMethod = keyof typeof CLOUD_ONLY_METHODS;
+/** Whether `method` (e.g. `relationships.patterns.list`) needs RushDB Cloud. */
+export declare const isCloudOnlyMethod: (method: string) => method is CloudOnlyMethod;

package/dist/direct/engine.d.ts

@@ -0,0 +1,45 @@
+import type { HttpClient } from '../network/HttpClient.js';
+/**
+ * Protocol operation envelope (v1) sent to `POST /protocol/v1/execute`.
+ */
+export type ProtocolEnvelope = {
+    protocolVersion: 1;
+    context?: {
+        scope?: string;
+    };
+    operation: Record<string, any>;
+};
+export type ProtocolResponse = {
+    response: {
+        kind: string;
+        [key: string]: any;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+};
+/**
+ * Direct engine transport: executes protocol operations against a standalone
+ * `rushdbd` (`/protocol/v1/execute`) over HTTP. This is the SDK's "direct
+ * mode" — no RushDB Cloud. `scope` is the tenant on a multitenant engine
+ * (`X-RushDB-Tenant`); auth is the engine token.
+ */
+export declare class DirectEngine {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly httpClient;
+    private readonly scope?;
+    constructor(config: {
+        engineUrl: string;
+        token: string;
+        httpClient: HttpClient;
+        scope?: string;
+    });
+    /**
+     * Runs one protocol operation and returns its `response`. A refused
+     * operation throws an `Error` with `status` (the engine's HTTP status) and a
+     * `"<status> <message>"` message, as a RushDB Cloud error does.
+     */
+    execute(operation: Record<string, any>): Promise<Record<string, any>>;
+}

package/dist/direct/router.d.ts

@@ -0,0 +1,20 @@
+import type { MakeRequestConfig } from '../network/HttpClient.js';
+import type { DirectEngine } from './engine.js';
+/**
+ * Direct mode answers the SDK's REST calls itself, with protocol operations
+ * against a standalone engine, so every SDK method keeps one code path and
+ * returns the same shapes in both modes. Each route mirrors what RushDB Cloud
+ * does for it; a Cloud-only route throws `CloudOnlyError` before anything is
+ * sent. No request ever goes to RushDB Cloud.
+ */
+type Body = Record<string, any>;
+/** An engine record (`{ id, label, properties, propertyTypes, score }`) in the SDK's shape. */
+export declare const toSdkRecord: (record: Body | undefined) => Body | undefined;
+/** The routes direct mode answers, as `METHOD pattern` (for tests and docs). */
+export declare const DIRECT_ROUTES: string[];
+/**
+ * A fetcher with `createFetcher`'s signature that answers from a standalone
+ * engine instead of sending the request to RushDB Cloud.
+ */
+export declare const createDirectFetcher: (engine: DirectEngine) => <Data extends Record<string, any> = Record<string, any>>(input: URL | string, { method, headers, requestData }: MakeRequestConfig<any>) => Promise<Data>;
+export {};

package/dist/direct/schema.d.ts

@@ -0,0 +1,48 @@
+import type { DirectEngine } from './engine.js';
+/**
+ * `ai.getSchema` and `ai.getSchemaMarkdown` in direct mode: the engine's
+ * `describe.schema` arranged per label exactly as RushDB Cloud arranges it,
+ * with each property's vector indexes attached.
+ */
+type Body = Record<string, any>;
+export type SchemaVectorIndex = {
+    id: string;
+    name: string;
+    sourceType: string;
+    similarityFunction: string;
+    dimensions: number;
+    status: string;
+    modelKey: string;
+};
+export type SchemaProperty = {
+    id: string;
+    name: string;
+    type: string;
+    isArray?: boolean;
+    min?: number | string;
+    max?: number | string;
+    values?: Array<string | number>;
+    recordsCount?: number;
+    vectorIndexes?: SchemaVectorIndex[];
+};
+export type SchemaRelationship = {
+    label: string;
+    type: string;
+    direction: 'in' | 'out';
+    count?: number;
+    properties?: Array<{
+        name: string;
+        type: string;
+        relationshipsCount?: number;
+    }>;
+};
+export type SchemaItem = {
+    label: string;
+    count: number;
+    properties: SchemaProperty[];
+    relationships: SchemaRelationship[];
+};
+export declare const buildSchema: (engine: DirectEngine, labels: string[] | undefined, toEmbeddingIndex: (index: Body) => Body) => Promise<SchemaItem[]>;
+/** The schema as compact Markdown tables, for an LLM to read. */
+export declare const buildSchemaMarkdown: (schema: SchemaItem[]) => string;
+export {};