@hydradb/sdk 2.1.3 → 2.1.5

package/README.md

@@ -235,8 +235,8 @@ metadata, checking processing status, reading graph relations, and deleting.
 
 `POST /context/ingest` (multipart) → `HandlerEnvelopeIngestionV2SourceUploadResponse`
 
-Ingest knowledge documents or memories. `documents` is a file upload; the other structured
-fields are JSON strings.
+Ingest knowledge documents or memories. `documents` is a list of file uploads (one request may
+carry several); the other structured fields are JSON strings.
 
 ```typescript
 import { createReadStream } from "fs";
@@ -244,11 +244,14 @@ import { createReadStream } from "fs";
 // Ingest a document file
 const res = await client.context.ingest({
   database: "acme-corp",                 // required
-  documents: createReadStream("handbook.pdf"),
+  documents: [createReadStream("handbook.pdf")],  // one entry per file
   collection: "hr",
   type: "knowledge",
-  // documentMetadata is a JSON *array* — one object per uploaded file.
-  documentMetadata: JSON.stringify([{ title: "Employee Handbook", author: "HR" }]),
+  // documentMetadata is a JSON *array* — one object per uploaded file. Your own
+  // per-document fields go under `additional_metadata`; the item's other top-level keys
+  // are the API's (metadata, evidence_kind, evidence_subject, id, relations, ...) —
+  // an unknown top-level key such as `title` is rejected with 400.
+  documentMetadata: JSON.stringify([{ additional_metadata: { title: "Employee Handbook", author: "HR" } }]),
   upsert: "true",                        // form field is a string
 });
 
@@ -265,9 +268,9 @@ await client.context.ingest({
 | Field              | Type                     | Notes |
 | ------------------ | ------------------------ | ----- |
 | `database`         | `string` (required)      | Database (tenant scope). Alias: `tenantId`. |
-| `documents`        | `Uploadable`             | File upload (stream, `Blob`, `Buffer`, etc.). |
+| `documents`        | `Uploadable[]`           | File uploads (stream, `Blob`, `Buffer`, etc.), one entry per file. |
 | `memories`         | `string`                 | JSON **array** string; each item needs `text` (or `user_assistant_pairs`). |
-| `documentMetadata` | `string`                 | JSON **array** string of per‑document metadata — one object per uploaded file (count must match). |
+| `documentMetadata` | `string`                 | JSON **array** string — one object per uploaded file (count must match). Put your own fields under `additional_metadata`; the API's item keys (`metadata`, `evidence_kind`, `evidence_subject`, `id`, `relations`, ...) may sit alongside it. Unknown top-level keys return 400. |
 | `appKnowledge`     | `string`                 | App‑knowledge items as a JSON **array** string (not raw text). |
 | `graphPayload`     | `string`                 | Pre‑computed graph payload. |
 | `collection`       | `string`                 | Collection (sub‑tenant scope). Alias: `subTenantId`. |

package/dist/Client.d.ts

@@ -51,7 +51,7 @@ export declare class HydraDBClient {
     listProviders(request?: HydraDB.ListProvidersRequest, requestOptions?: HydraDBClient.RequestOptions): core.HttpResponsePromise<HydraDB.HandlerProviderListResponse>;
     private __listProviders;
     /**
-     * Unified query endpoint that dispatches across type (knowledge/memory/all) and query_by (hybrid/text). Prefer sub_tenant_ids for sub-tenant scoping; legacy sub_tenant_id is deprecated for /query and cannot be sent together with sub_tenant_ids.
+     * Unified query endpoint that dispatches across type and query_by (hybrid/text). Optionally filter by one or more exact document titles with `titles`; these are resolved to source IDs before normal retrieval. Filter with `attributes` (an operator language, pushed into the vector search); `metadata_filters` is deprecated in favour of it and still works. On a SPLIT database `type` is knowledge (the default), memory, or all (both, merged), unchanged. On a UNIFIED database there is one corpus: omit `type`, or send `unified` (`all` is accepted and means the same); knowledge and memory are rejected there. Prefer sub_tenant_ids for sub-tenant scoping; legacy sub_tenant_id is deprecated for /query and cannot be sent together with sub_tenant_ids.
      *
      * @param {HydraDB.SearchQueryRequest} request
      * @param {HydraDBClient.RequestOptions} requestOptions - Request-specific configuration.

package/dist/Client.js

@@ -180,7 +180,7 @@ class HydraDBClient {
         return (0, handleNonStatusCodeError_js_1.handleNonStatusCodeError)(_response.error, _response.rawResponse, "GET", "/connectors/providers");
     }
     /**
-     * Unified query endpoint that dispatches across type (knowledge/memory/all) and query_by (hybrid/text). Prefer sub_tenant_ids for sub-tenant scoping; legacy sub_tenant_id is deprecated for /query and cannot be sent together with sub_tenant_ids.
+     * Unified query endpoint that dispatches across type and query_by (hybrid/text). Optionally filter by one or more exact document titles with `titles`; these are resolved to source IDs before normal retrieval. Filter with `attributes` (an operator language, pushed into the vector search); `metadata_filters` is deprecated in favour of it and still works. On a SPLIT database `type` is knowledge (the default), memory, or all (both, merged), unchanged. On a UNIFIED database there is one corpus: omit `type`, or send `unified` (`all` is accepted and means the same); knowledge and memory are rejected there. Prefer sub_tenant_ids for sub-tenant scoping; legacy sub_tenant_id is deprecated for /query and cannot be sent together with sub_tenant_ids.
      *
      * @param {HydraDB.SearchQueryRequest} request
      * @param {HydraDBClient.RequestOptions} requestOptions - Request-specific configuration.

package/dist/api/client/requests/SearchQueryRequest.d.ts

@@ -4,10 +4,39 @@ import type * as HydraDB from "../../index.js";
  *     {}
  */
 export interface SearchQueryRequest {
+    /**
+     * ACL scopes retrieval to documents the given principals may access
+     * (PRO-1684 document ACLs): a document matches when its stored ACL is
+     * empty (unrestricted, pre-RBAC content and connectors without permission
+     * support), contains __public__, or intersects these principals. Entries
+     * are bare emails or prefixed principals (user_email:/group:/domain:).
+     * Omitted, empty, or ["*"] disables ACL filtering entirely, today's
+     * behavior. Like IDs, the resulting clause survives the metadata
+     * zero-result retry. An entry that is not a known principal fails CLOSED:
+     * it matches only public and unrestricted documents, never restricted.
+     */
+    acl?: string[];
     /** Optional context string prepended to the query to improve retrieval relevance. */
     additionalContext?: string;
     /** Weighting balance between dense and sparse retrieval in hybrid mode. `"auto"` lets HydraDB choose; a number from 0 (full BM25) to 1 (full dense) sets it explicitly. */
     alpha?: unknown;
+    /**
+     * Attributes is the go-forward metadata filter: a MongoDB-like operator query
+     * ($eq/$ne/$gt/$gte/$lt/$lte/$in/$nin/$and/$or/$not/$exists) over the
+     * database attributes, translated to a safe Milvus scalar pre-filter by
+     * BuildAttributesFilterExpr (PRO-1618). It composes (AND) with the
+     * deprecated metadata_filters while both exist. Field names are allowlisted
+     * and values escaped, so it is injection-safe.
+     *
+     * It is applied everywhere metadata_filters is, and nowhere else: the
+     * chunks a query returns, the additional context and forceful-relation
+     * chunks (the fail-closed post-filter net in the service), and the graph
+     * paths, which the graph lane prunes by resolving every source a path
+     * cites and dropping the paths that touch one failing the predicate
+     * (disallowedGraphSources). Product decision 2026-09-04: `attributes`
+     * behaves like `metadata_filters` on every part of the response.
+     */
+    attributes?: Record<string, unknown>;
     /** Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated). */
     collection?: string;
     /** Preferred /query scope selector. Send either a list of collection IDs for equal normalized weighting, or an object mapping collection ID to a positive relative ranking weight with at most one decimal place. Do not send together with the deprecated sub_tenant_ids or sub_tenant_id. */
@@ -58,15 +87,28 @@ export interface SearchQueryRequest {
     /** Number of adjacent chunks to pull alongside each matched chunk for additional context. */
     numRelatedChunks?: number;
     operator?: HydraDB.SearchOperator;
+    /**
+     * ProfileEntityType/ProfileNamespace refine the subject's graph identity;
+     * defaults ("PERSON"/"users") cover the common case of a person subject.
+     */
+    profileEntityType?: string;
+    profileNamespace?: string;
+    /**
+     * ProfileSubject names the entity whose compiled profile should ride the
+     * response as profile_context/profile_filter (PRO-1797). Payload-only:
+     * chunk ranking is never altered. Omitted = no profile block. Dark until
+     * the repo-level ENTITY_PROFILE_CONTEXT_ENABLED flag is on.
+     */
+    profileSubject?: string;
     /** Natural-language search query. */
     query?: string;
-    /** Whether to include app-aware knowledge retrieval. Applies to knowledge hybrid queries. */
+    /** Whether to include app-aware knowledge retrieval. Applies to knowledge hybrid queries. Defaults to true when omitted; pass false to search files only. */
     queryApps?: boolean;
     /** Retrieval method to use for the query. */
     queryBy?: HydraDB.SearchQueryBy;
     /** Whether to force relation expansion for graph-aware query retrieval. Defaults to true when omitted. */
     queryForcefulRelations?: boolean;
-    /** Recency boost applied to ranking. 0 disables it; higher values favour more recent sources. */
+    /** Recency boost applied to ranking (0.0-1.0). Omit it to get the always-on default baseline of 0.40 (a bounded <=40% swing on normalized relevance — it reorders within a relevance gap of up to 0.40 but never buries a more strongly relevant result); send 0 to disable recency entirely; higher values favour more recent sources more strongly. */
     recencyBias?: number;
     /** Deprecated for /query (since 2.0.1). Use collection for a single scope or collections for multiple. Backwards-compatible and will be removed in a future version. Do not send together with a multi-scope selector. */
     subTenantId?: string;
@@ -94,6 +136,8 @@ export interface SearchQueryRequest {
     temporalReasoning?: boolean;
     /** deprecated: use database */
     tenantId?: string;
-    /** Corpus to query: knowledge, memory, or all. */
+    /** Optional exact document-title filter. Values are matched case-insensitively and ORed, resolved to source IDs, then the normal query pipeline runs within that source scope. When ids is also supplied, the two filters are intersected. */
+    titles?: string[];
+    /** Corpus to query. Split database: knowledge (the default), memory, or all (both, merged). Unified database: omit it, or send unified (all is accepted and means the same); knowledge and memory are rejected there. */
     type?: HydraDB.SearchSourceType;
 }

package/dist/api/resources/connectors/client/Client.d.ts

@@ -94,7 +94,7 @@ export declare class ConnectorsClient {
     delete(request: HydraDB.DeleteConnectorsRequest, requestOptions?: ConnectorsClient.RequestOptions): core.HttpResponsePromise<HydraDB.HandlerConnectorDeleteResponse>;
     private __delete;
     /**
-     * Update a connector's mutable settings. `sync_interval_seconds` sets the cadence at which the scheduler starts incremental syncs: the allowed range is provider-aware and returned in the response; values outside it are rejected rather than clamped; 0 resets to the provider default; changing it re-anchors the next sync so a shorter cadence takes effect immediately. `credentials` reconnects the connector in place: send the provider's full credential set (what create accepts); supplied keys replace their stored values, other stored keys survive, the bundle is re-validated against the provider's credential schema, and a pending needs-reauth flag is cleared — the connector keeps its id, resources, and sync cursors.
+     * Update a connector's mutable settings. `sync_interval_seconds` sets the cadence at which the scheduler starts incremental syncs: the allowed range is provider-aware and returned in the response; values outside it are rejected rather than clamped; 0 resets to the provider default; changing it re-anchors the next sync so a shorter cadence takes effect immediately. `credentials` reconnects the connector in place: send the provider's full credential set (what create accepts); supplied keys replace their stored values, other stored keys survive, the bundle is re-validated against the provider's credential schema, and a pending needs-reauth flag is cleared — the connector keeps its id, resources, and sync cursors. `custom_instructions` replaces the free-text steering applied when this connector's documents are ingested (an explicit empty string clears it); the change applies from the next sync cycle and does not re-process already-ingested documents. When several fields are supplied together they are validated up front and applied atomically: an invalid value rejects the whole request with nothing changed.
      *
      * @param {HydraDB.HandlerConnectorUpdateReq} request
      * @param {ConnectorsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -174,6 +174,7 @@ export declare class ConnectorsClient {
      * @throws {@link HydraDB.NotFoundError}
      * @throws {@link HydraDB.InternalServerError}
      * @throws {@link HydraDB.BadGatewayError}
+     * @throws {@link HydraDB.ServiceUnavailableError}
      *
      * @example
      *     await client.connectors.discover({
@@ -182,6 +183,23 @@ export declare class ConnectorsClient {
      */
     discover(request: HydraDB.DiscoverConnectorsRequest, requestOptions?: ConnectorsClient.RequestOptions): core.HttpResponsePromise<HydraDB.HandlerDiscoverResponseBody>;
     private __discover;
+    /**
+     * Stop scheduling syncs and backfills for a connector until it is resumed. A sync already running is allowed to finish. Cursors are preserved, so resuming continues from where each resource left off.
+     *
+     * @param {HydraDB.PauseConnectorsRequest} request
+     * @param {ConnectorsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link HydraDB.NotFoundError}
+     * @throws {@link HydraDB.ConflictError}
+     * @throws {@link HydraDB.InternalServerError}
+     *
+     * @example
+     *     await client.connectors.pause({
+     *         id: "HydraDoc1234"
+     *     })
+     */
+    pause(request: HydraDB.PauseConnectorsRequest, requestOptions?: ConnectorsClient.RequestOptions): core.HttpResponsePromise<HydraDB.HandlerConnectorPauseResponse>;
+    private __pause;
     /**
      * List the configured resources for a connector.
      *
@@ -235,7 +253,45 @@ export declare class ConnectorsClient {
     deleteResource(request: HydraDB.DeleteResourceConnectorsRequest, requestOptions?: ConnectorsClient.RequestOptions): core.HttpResponsePromise<HydraDB.HandlerResourceDeleteResponse>;
     private __deleteResource;
     /**
-     * Report whether a connector is working, in one call: a rollup status (healthy, degraded, failed, checking) plus per-resource detail. `degraded` means the connector is syncing but at least one configured resource is failing — the state that is otherwise invisible, because a connector whose resources partly fail still reports an idle sync status and no error.
+     * Updates per-resource settings. `acl` sets the customer-declared ACL for one connector resource (PRO-1684): the rule is normalized (emails prefixed, __public__ dominates, explicit-empty becomes __private__), persisted on the resource, and applied to enforcement immediately via the resource's ACL row, every already-indexed document of the resource is governed by it on the next query, with no re-sync. For providers with provider-derived ACL capture enabled, the provider's own ACL takes precedence again at the next sync; the rule is the standing fallback. `custom_instructions` sets the resource-level ingestion-instructions override (max 4000 characters): when set it replaces the connector-level custom_instructions for documents synced from this resource, an explicit empty string clears the override back to inheriting the connector's value, and changes apply from the next sync cycle. At least one field must be supplied; omitted fields are left unchanged.
+     *
+     * @param {HydraDB.UpdateResourceAclConnectorsRequest} request
+     * @param {ConnectorsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link HydraDB.BadRequestError}
+     * @throws {@link HydraDB.NotFoundError}
+     * @throws {@link HydraDB.InternalServerError}
+     *
+     * @example
+     *     await client.connectors.updateResourceAcl({
+     *         id: "HydraDoc1234",
+     *         resourceId: "C0123456789",
+     *         body: {
+     *             "key": "value"
+     *         }
+     *     })
+     */
+    updateResourceAcl(request: HydraDB.UpdateResourceAclConnectorsRequest, requestOptions?: ConnectorsClient.RequestOptions): core.HttpResponsePromise<Record<string, unknown>>;
+    private __updateResourceAcl;
+    /**
+     * Return a paused connector to the schedule and make it due immediately. Each resource continues from its committed cursor, so data created during the pause is collected on the next cycle rather than skipped.
+     *
+     * @param {HydraDB.ResumeConnectorsRequest} request
+     * @param {ConnectorsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link HydraDB.NotFoundError}
+     * @throws {@link HydraDB.ConflictError}
+     * @throws {@link HydraDB.InternalServerError}
+     *
+     * @example
+     *     await client.connectors.resume({
+     *         id: "HydraDoc1234"
+     *     })
+     */
+    resume(request: HydraDB.ResumeConnectorsRequest, requestOptions?: ConnectorsClient.RequestOptions): core.HttpResponsePromise<HydraDB.HandlerConnectorPauseResponse>;
+    private __resume;
+    /**
+     * Report whether a connector is working, in one call: a rollup status (healthy, degraded, failed, checking) plus per-resource detail. `degraded` means the connector is scheduled but not fully working: at least one configured resource is failing, or the latest sync cycle failed after the resources reported (in which case `error` carries the failure and `retryable` says whether waiting can fix it). `failed` means only the user can fix it: a rejected credential, a blocked connector, or a terminal cycle failure.
      *
      * @param {HydraDB.StatusConnectorsRequest} request
      * @param {ConnectorsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -268,4 +324,48 @@ export declare class ConnectorsClient {
      */
     sync(request: HydraDB.SyncConnectorsRequest, requestOptions?: ConnectorsClient.RequestOptions): core.HttpResponsePromise<HydraDB.HandlerConnectorSyncResponse>;
     private __sync;
+    /**
+     * List metadata and field names for credentials already used by connectors in the current workspace.
+     *
+     * @param {ConnectorsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @example
+     *     await client.connectors.listConnectorCredentials()
+     */
+    listConnectorCredentials(requestOptions?: ConnectorsClient.RequestOptions): core.HttpResponsePromise<HydraDB.HandlerVaultCredentialListResponse>;
+    private __listConnectorCredentials;
+    /**
+     * Update fields on the credential currently used by a connector. Owner-only human action.
+     *
+     * @param {HydraDB.HandlerVaultCredentialUpdateReq} request
+     * @param {ConnectorsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link HydraDB.NotFoundError}
+     *
+     * @example
+     *     await client.connectors.updateConnectorCredentials({
+     *         id: "HydraDoc1234",
+     *         credentials: {
+     *             "api_token": "xoxb-..."
+     *         }
+     *     })
+     */
+    updateConnectorCredentials(request: HydraDB.HandlerVaultCredentialUpdateReq, requestOptions?: ConnectorsClient.RequestOptions): core.HttpResponsePromise<HydraDB.HandlerVaultCredentialUpdateResponse>;
+    private __updateConnectorCredentials;
+    /**
+     * Reveal one field from the credential currently used by a connector in the workspace. The response must never be cached.
+     *
+     * @param {HydraDB.HandlerVaultCredentialRevealReq} request
+     * @param {ConnectorsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link HydraDB.NotFoundError}
+     *
+     * @example
+     *     await client.connectors.revealAConnectorCredentialValue({
+     *         id: "HydraDoc1234",
+     *         field: "field"
+     *     })
+     */
+    revealAConnectorCredentialValue(request: HydraDB.HandlerVaultCredentialRevealReq, requestOptions?: ConnectorsClient.RequestOptions): core.HttpResponsePromise<HydraDB.HandlerVaultCredentialRevealResponse>;
+    private __revealAConnectorCredentialValue;
 }