@hydradb/sdk 2.1.1 → 2.1.3

package/dist/api/types/SourcesMemoryDeleteResponse.d.ts

@@ -6,7 +6,15 @@ export interface SourcesMemoryDeleteResponse {
     message?: string;
     /** Per-item results. */
     results?: HydraDB.SourcesSourceDeleteResultItem[];
-    /** Whether the request succeeded. */
+    /**
+     * Deprecated for API clients: whether the REQUEST succeeded is the HTTP
+     * status code, or equivalently the envelope's top-level `success`. Whether
+     * anything was actually removed is deleted_count (0 means the ids matched
+     * nothing) and per-id results[].deleted / results[].error. This flag is
+     * true even for a delete that removed nothing, so it cannot answer either
+     * question on its own. Still emitted unchanged for existing clients
+     * (PRO-1208).
+     */
     success?: boolean;
     /** Number of memory items deleted. */
     userMemoryDeleted?: number;

package/dist/api/types/TenantsCollectionStats.d.ts

@@ -1,6 +1,4 @@
 export interface TenantsCollectionStats {
-    /** Embedding vector dimension for this collection. */
-    dimensions?: number;
     /** Total number of indexed rows in this collection. */
     rowCount?: number;
 }

package/dist/api/types/TenantsCustomPropertyDefinition.d.ts

@@ -2,8 +2,6 @@ import type * as HydraDB from "../index.js";
 export interface TenantsCustomPropertyDefinition {
     /** Milvus data type for this metadata field. */
     dataType?: HydraDB.TenantsMilvusDataType;
-    /** Whether to enable text analysis (tokenization) for BM25 search on this field. */
-    enableAnalyzer?: boolean;
     /** Whether to enable semantic (dense) embedding search on this field. */
     enableDenseEmbedding?: boolean;
     /** Whether to enable exact-match filtering on this field. */

package/dist/api/types/TenantsInfraV2.d.ts

@@ -2,7 +2,9 @@ import type * as HydraDB from "../index.js";
 export interface TenantsInfraV2 {
     /** Whether the graph store is healthy for this database. */
     graphStatus?: boolean;
-    /** Whether the sync scheduler is healthy for this database. */
+    /** Derived readiness flag: true only when scheduler_status (lifecycle provisioning finished), graph_status, and both vectorstore_status.knowledge and vectorstore_status.memories are true — i.e. the database is fully provisioned and ready to accept ingestion and serve queries. Database creation is asynchronous: collections may appear before provisioning completes, so poll GET /databases/status until this is true before ingesting or querying. */
+    readyForIngestion?: boolean;
+    /** Whether lifecycle provisioning has finished for this database (creation_status is ready). False while the database is still being created, even if individual collections already exist. */
     schedulerStatus?: boolean;
     vectorstoreStatus?: HydraDB.TenantsVectorstoreStatusV2;
 }

package/dist/api/types/TenantsTenantMetadataSchemaResponse.d.ts

@@ -0,0 +1,7 @@
+import type * as HydraDB from "../index.js";
+export interface TenantsTenantMetadataSchemaResponse {
+    /** Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated). */
+    database?: string;
+    fields?: HydraDB.TenantsCustomPropertyDefinition[];
+    tenantId?: string;
+}

package/dist/api/types/TenantsTenantMetadataSchemaResponse.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/types/WebhooksDeliveryItem.d.ts

@@ -19,4 +19,10 @@ export interface WebhooksDeliveryItem {
     status?: string;
     /** RFC3339 timestamp of the most recent update. */
     updatedAt?: string;
+    /**
+     * Endpoint this delivery was aimed at. Attributes history to the endpoint
+     * that was registered when the delivery was created, rather than to whatever
+     * is registered now, so a changed URL does not inherit the old one's failures.
+     */
+    webhookUrl?: string;
 }

package/dist/api/types/WebhooksSigningSecretResponse.d.ts

@@ -0,0 +1,8 @@
+export interface WebhooksSigningSecretResponse {
+    /** Whether the returned secret was generated by HydraDB rather than supplied by you. */
+    generated?: boolean;
+    /** Human-readable result message. */
+    message?: string;
+    /** Secret used to sign webhook payloads. Deliveries carry `X-HydraDB-Signature: sha256=<hex>`, the HMAC-SHA256 of the raw request body keyed by this secret. Minimum 16 characters when you supply your own; omit it and one is generated for you. On registration, omitting this field preserves any existing secret - to disable signing, call DELETE /webhooks/indexing/signing-secret. */
+    signingSecret?: string;
+}

package/dist/api/types/WebhooksSigningSecretResponse.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/types/WebhooksWebhookRegisterResponse.d.ts

@@ -5,6 +5,8 @@ export interface WebhooksWebhookRegisterResponse {
     message?: string;
     /** Whether a webhook is registered for this API key. */
     registered?: boolean;
+    /** Secret used to sign webhook payloads. Deliveries carry `X-HydraDB-Signature: sha256=<hex>`, the HMAC-SHA256 of the raw request body keyed by this secret. Minimum 16 characters when you supply your own; omit it and one is generated for you. On registration, omitting this field preserves any existing secret - to disable signing, call DELETE /webhooks/indexing/signing-secret. */
+    signingSecret?: string;
     /** Whether a signing secret has been configured for payload verification. */
     signingSecretConfigured?: boolean;
     /** Registered endpoint URL that receives webhook event deliveries. */

package/dist/api/types/index.d.ts

@@ -1,6 +1,15 @@
-export * from "./ConnectorsConnector.js";
 export * from "./ConnectorsResource.js";
 export * from "./DashboardPaginationMeta.js";
+export * from "./FeedbackGroundTruth.js";
+export * from "./FeedbackRating.js";
+export * from "./FeedbackSource.js";
+export * from "./FeedbackSubmitRequest.js";
+export * from "./FeedbackSubmitRequestFeedback.js";
+export * from "./FeedbackSubmitRequestGroundTruth.js";
+export * from "./FeedbackSubmitRequestGroundTruthGroundTruth.js";
+export * from "./FeedbackSubmitRequestGroundTruthGroundTruthAnswer.js";
+export * from "./FeedbackSubmitRequestGroundTruthGroundTruthSourceIds.js";
+export * from "./FeedbackSubmitResponse.js";
 export * from "./FetchV2SourceFetchResponse.js";
 export * from "./GithubComHydradbHydradbApplicationInternalServiceMetadataEditResult.js";
 export * from "./GraphEntity.js";
@@ -8,13 +17,31 @@ export * from "./GraphGraphRelationsResponse.js";
 export * from "./GraphRelationEvidence.js";
 export * from "./GraphTripletWithEvidence.js";
 export * from "./HandlerApiError.js";
+export * from "./HandlerCatalogConnector.js";
+export * from "./HandlerConfigureResponse.js";
+export * from "./HandlerConfigureResponseMeta.js";
+export * from "./HandlerConnectorApiView.js";
+export * from "./HandlerConnectorCatalogResponse.js";
+export * from "./HandlerConnectorCreateResponse.js";
+export * from "./HandlerConnectorDeleteResponse.js";
+export * from "./HandlerConnectorListResponse.js";
+export * from "./HandlerConnectorResourceStatus.js";
+export * from "./HandlerConnectorResourcesResponse.js";
+export * from "./HandlerConnectorStatusError.js";
+export * from "./HandlerConnectorStatusResponse.js";
+export * from "./HandlerConnectorSyncResponse.js";
+export * from "./HandlerConnectorUpdateResponse.js";
+export * from "./HandlerCredentialsUpdateResponse.js";
 export * from "./HandlerDeprecationNotice.js";
+export * from "./HandlerDiscoveredResourceDto.js";
+export * from "./HandlerDiscoverResponseBody.js";
+export * from "./HandlerEnvelopeFeedbackSubmitResponse.js";
 export * from "./HandlerEnvelopeFetchV2SourceFetchResponse.js";
 export * from "./HandlerEnvelopeGithubComHydradbHydradbApplicationInternalServiceMetadataEditResult.js";
 export * from "./HandlerEnvelopeGraphGraphRelationsResponse.js";
 export * from "./HandlerEnvelopeIngestionV2BatchProcessingStatus.js";
-export * from "./HandlerEnvelopeIngestionV2SourceUploadResponse.js";
-export * from "./HandlerEnvelopeListV2SourceListResponse.js";
+export * from "./HandlerEnvelopeIngestionV2IngestResponse.js";
+export * from "./HandlerEnvelopeListV2ListResponse.js";
 export * from "./HandlerEnvelopeSearchV2RetrievalResult.js";
 export * from "./HandlerEnvelopeSourcesMemoryDeleteResponse.js";
 export * from "./HandlerEnvelopeTenantsInfraStatusResponseV2.js";
@@ -22,27 +49,36 @@ export * from "./HandlerEnvelopeTenantsSubTenantIdsResponse.js";
 export * from "./HandlerEnvelopeTenantsTenantCreateAcceptedResponse.js";
 export * from "./HandlerEnvelopeTenantsTenantDeleteResponse.js";
 export * from "./HandlerEnvelopeTenantsTenantIdsResponse.js";
+export * from "./HandlerEnvelopeTenantsTenantMetadataSchemaResponse.js";
 export * from "./HandlerEnvelopeTenantsTenantStatsResponse.js";
 export * from "./HandlerEnvelopeWebhooksDeliveryItem.js";
 export * from "./HandlerEnvelopeWebhooksDeliveryListResponse.js";
 export * from "./HandlerEnvelopeWebhooksRetryResponse.js";
+export * from "./HandlerEnvelopeWebhooksSigningSecretResponse.js";
 export * from "./HandlerEnvelopeWebhooksWebhookDeleteResponse.js";
 export * from "./HandlerEnvelopeWebhooksWebhookGetResponse.js";
 export * from "./HandlerEnvelopeWebhooksWebhookRegisterResponse.js";
 export * from "./HandlerEnvelopeWebhooksWebhookTestResponse.js";
 export * from "./HandlerErrorDetail.js";
+export * from "./HandlerErrorEnvelopeSourcesMemoryDeleteResponse.js";
+export * from "./HandlerErrorMeta.js";
 export * from "./HandlerErrorResponse.js";
 export * from "./HandlerMetadataSchemaUpdateResponse.js";
+export * from "./HandlerProviderListResponse.js";
+export * from "./HandlerResourceDeleteResponse.js";
 export * from "./HandlerResourceMapping.js";
+export * from "./HandlerResourceMappingSyncMode.js";
 export * from "./HandlerResponseMeta.js";
+export * from "./HandlerTableConfigEntry.js";
 export * from "./IngestionSourceStatus.js";
 export * from "./IngestionV2BatchProcessingStatus.js";
+export * from "./IngestionV2IngestResponse.js";
+export * from "./IngestionV2IngestResultItem.js";
 export * from "./IngestionV2ProcessingStatus.js";
-export * from "./IngestionV2SourceUploadResponse.js";
-export * from "./IngestionV2SourceUploadResultItem.js";
 export * from "./ListContentFilter.js";
-export * from "./ListSourceListResponse.js";
-export * from "./ListV2SourceListResponse.js";
+export * from "./ListV2ListResponse.js";
+export * from "./ListV2MemoryItem.js";
+export * from "./ListV2SourceItem.js";
 export * from "./SearchGraphContext.js";
 export * from "./SearchMetadataFilters.js";
 export * from "./SearchOperator.js";
@@ -54,6 +90,10 @@ export * from "./SearchRecallMode.js";
 export * from "./SearchScoredPathResponse.js";
 export * from "./SearchSourceInfo.js";
 export * from "./SearchSourceType.js";
+export * from "./SearchTemporalDuration.js";
+export * from "./SearchTemporalFact.js";
+export * from "./SearchTemporalFilterInfo.js";
+export * from "./SearchTemporalIntentOverride.js";
 export * from "./SearchV2Chunk.js";
 export * from "./SearchV2RetrievalResult.js";
 export * from "./SourcesMemoryDeleteResponse.js";
@@ -68,11 +108,13 @@ export * from "./TenantsSubTenantIdsResponse.js";
 export * from "./TenantsTenantCreateAcceptedResponse.js";
 export * from "./TenantsTenantDeleteResponse.js";
 export * from "./TenantsTenantIdsResponse.js";
+export * from "./TenantsTenantMetadataSchemaResponse.js";
 export * from "./TenantsTenantStatsResponse.js";
 export * from "./TenantsVectorstoreStatusV2.js";
 export * from "./WebhooksDeliveryItem.js";
 export * from "./WebhooksDeliveryListResponse.js";
 export * from "./WebhooksRetryResponse.js";
+export * from "./WebhooksSigningSecretResponse.js";
 export * from "./WebhooksWebhookDeleteResponse.js";
 export * from "./WebhooksWebhookGetResponse.js";
 export * from "./WebhooksWebhookRegisterResponse.js";

package/dist/api/types/index.js

@@ -14,9 +14,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./ConnectorsConnector.js"), exports);
 __exportStar(require("./ConnectorsResource.js"), exports);
 __exportStar(require("./DashboardPaginationMeta.js"), exports);
+__exportStar(require("./FeedbackGroundTruth.js"), exports);
+__exportStar(require("./FeedbackRating.js"), exports);
+__exportStar(require("./FeedbackSource.js"), exports);
+__exportStar(require("./FeedbackSubmitRequest.js"), exports);
+__exportStar(require("./FeedbackSubmitRequestFeedback.js"), exports);
+__exportStar(require("./FeedbackSubmitRequestGroundTruth.js"), exports);
+__exportStar(require("./FeedbackSubmitRequestGroundTruthGroundTruth.js"), exports);
+__exportStar(require("./FeedbackSubmitRequestGroundTruthGroundTruthAnswer.js"), exports);
+__exportStar(require("./FeedbackSubmitRequestGroundTruthGroundTruthSourceIds.js"), exports);
+__exportStar(require("./FeedbackSubmitResponse.js"), exports);
 __exportStar(require("./FetchV2SourceFetchResponse.js"), exports);
 __exportStar(require("./GithubComHydradbHydradbApplicationInternalServiceMetadataEditResult.js"), exports);
 __exportStar(require("./GraphEntity.js"), exports);
@@ -24,13 +33,31 @@ __exportStar(require("./GraphGraphRelationsResponse.js"), exports);
 __exportStar(require("./GraphRelationEvidence.js"), exports);
 __exportStar(require("./GraphTripletWithEvidence.js"), exports);
 __exportStar(require("./HandlerApiError.js"), exports);
+__exportStar(require("./HandlerCatalogConnector.js"), exports);
+__exportStar(require("./HandlerConfigureResponse.js"), exports);
+__exportStar(require("./HandlerConfigureResponseMeta.js"), exports);
+__exportStar(require("./HandlerConnectorApiView.js"), exports);
+__exportStar(require("./HandlerConnectorCatalogResponse.js"), exports);
+__exportStar(require("./HandlerConnectorCreateResponse.js"), exports);
+__exportStar(require("./HandlerConnectorDeleteResponse.js"), exports);
+__exportStar(require("./HandlerConnectorListResponse.js"), exports);
+__exportStar(require("./HandlerConnectorResourceStatus.js"), exports);
+__exportStar(require("./HandlerConnectorResourcesResponse.js"), exports);
+__exportStar(require("./HandlerConnectorStatusError.js"), exports);
+__exportStar(require("./HandlerConnectorStatusResponse.js"), exports);
+__exportStar(require("./HandlerConnectorSyncResponse.js"), exports);
+__exportStar(require("./HandlerConnectorUpdateResponse.js"), exports);
+__exportStar(require("./HandlerCredentialsUpdateResponse.js"), exports);
 __exportStar(require("./HandlerDeprecationNotice.js"), exports);
+__exportStar(require("./HandlerDiscoveredResourceDto.js"), exports);
+__exportStar(require("./HandlerDiscoverResponseBody.js"), exports);
+__exportStar(require("./HandlerEnvelopeFeedbackSubmitResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeFetchV2SourceFetchResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeGithubComHydradbHydradbApplicationInternalServiceMetadataEditResult.js"), exports);
 __exportStar(require("./HandlerEnvelopeGraphGraphRelationsResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeIngestionV2BatchProcessingStatus.js"), exports);
-__exportStar(require("./HandlerEnvelopeIngestionV2SourceUploadResponse.js"), exports);
-__exportStar(require("./HandlerEnvelopeListV2SourceListResponse.js"), exports);
+__exportStar(require("./HandlerEnvelopeIngestionV2IngestResponse.js"), exports);
+__exportStar(require("./HandlerEnvelopeListV2ListResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeSearchV2RetrievalResult.js"), exports);
 __exportStar(require("./HandlerEnvelopeSourcesMemoryDeleteResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeTenantsInfraStatusResponseV2.js"), exports);
@@ -38,27 +65,36 @@ __exportStar(require("./HandlerEnvelopeTenantsSubTenantIdsResponse.js"), exports
 __exportStar(require("./HandlerEnvelopeTenantsTenantCreateAcceptedResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeTenantsTenantDeleteResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeTenantsTenantIdsResponse.js"), exports);
+__exportStar(require("./HandlerEnvelopeTenantsTenantMetadataSchemaResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeTenantsTenantStatsResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeWebhooksDeliveryItem.js"), exports);
 __exportStar(require("./HandlerEnvelopeWebhooksDeliveryListResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeWebhooksRetryResponse.js"), exports);
+__exportStar(require("./HandlerEnvelopeWebhooksSigningSecretResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeWebhooksWebhookDeleteResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeWebhooksWebhookGetResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeWebhooksWebhookRegisterResponse.js"), exports);
 __exportStar(require("./HandlerEnvelopeWebhooksWebhookTestResponse.js"), exports);
 __exportStar(require("./HandlerErrorDetail.js"), exports);
+__exportStar(require("./HandlerErrorEnvelopeSourcesMemoryDeleteResponse.js"), exports);
+__exportStar(require("./HandlerErrorMeta.js"), exports);
 __exportStar(require("./HandlerErrorResponse.js"), exports);
 __exportStar(require("./HandlerMetadataSchemaUpdateResponse.js"), exports);
+__exportStar(require("./HandlerProviderListResponse.js"), exports);
+__exportStar(require("./HandlerResourceDeleteResponse.js"), exports);
 __exportStar(require("./HandlerResourceMapping.js"), exports);
+__exportStar(require("./HandlerResourceMappingSyncMode.js"), exports);
 __exportStar(require("./HandlerResponseMeta.js"), exports);
+__exportStar(require("./HandlerTableConfigEntry.js"), exports);
 __exportStar(require("./IngestionSourceStatus.js"), exports);
 __exportStar(require("./IngestionV2BatchProcessingStatus.js"), exports);
+__exportStar(require("./IngestionV2IngestResponse.js"), exports);
+__exportStar(require("./IngestionV2IngestResultItem.js"), exports);
 __exportStar(require("./IngestionV2ProcessingStatus.js"), exports);
-__exportStar(require("./IngestionV2SourceUploadResponse.js"), exports);
-__exportStar(require("./IngestionV2SourceUploadResultItem.js"), exports);
 __exportStar(require("./ListContentFilter.js"), exports);
-__exportStar(require("./ListSourceListResponse.js"), exports);
-__exportStar(require("./ListV2SourceListResponse.js"), exports);
+__exportStar(require("./ListV2ListResponse.js"), exports);
+__exportStar(require("./ListV2MemoryItem.js"), exports);
+__exportStar(require("./ListV2SourceItem.js"), exports);
 __exportStar(require("./SearchGraphContext.js"), exports);
 __exportStar(require("./SearchMetadataFilters.js"), exports);
 __exportStar(require("./SearchOperator.js"), exports);
@@ -70,6 +106,10 @@ __exportStar(require("./SearchRecallMode.js"), exports);
 __exportStar(require("./SearchScoredPathResponse.js"), exports);
 __exportStar(require("./SearchSourceInfo.js"), exports);
 __exportStar(require("./SearchSourceType.js"), exports);
+__exportStar(require("./SearchTemporalDuration.js"), exports);
+__exportStar(require("./SearchTemporalFact.js"), exports);
+__exportStar(require("./SearchTemporalFilterInfo.js"), exports);
+__exportStar(require("./SearchTemporalIntentOverride.js"), exports);
 __exportStar(require("./SearchV2Chunk.js"), exports);
 __exportStar(require("./SearchV2RetrievalResult.js"), exports);
 __exportStar(require("./SourcesMemoryDeleteResponse.js"), exports);
@@ -84,11 +124,13 @@ __exportStar(require("./TenantsSubTenantIdsResponse.js"), exports);
 __exportStar(require("./TenantsTenantCreateAcceptedResponse.js"), exports);
 __exportStar(require("./TenantsTenantDeleteResponse.js"), exports);
 __exportStar(require("./TenantsTenantIdsResponse.js"), exports);
+__exportStar(require("./TenantsTenantMetadataSchemaResponse.js"), exports);
 __exportStar(require("./TenantsTenantStatsResponse.js"), exports);
 __exportStar(require("./TenantsVectorstoreStatusV2.js"), exports);
 __exportStar(require("./WebhooksDeliveryItem.js"), exports);
 __exportStar(require("./WebhooksDeliveryListResponse.js"), exports);
 __exportStar(require("./WebhooksRetryResponse.js"), exports);
+__exportStar(require("./WebhooksSigningSecretResponse.js"), exports);
 __exportStar(require("./WebhooksWebhookDeleteResponse.js"), exports);
 __exportStar(require("./WebhooksWebhookGetResponse.js"), exports);
 __exportStar(require("./WebhooksWebhookRegisterResponse.js"), exports);

package/dist/helpers/buildString.js

@@ -25,6 +25,43 @@ function sourceLabel(chunk) {
     }
     return sourceId;
 }
+/**
+ * Render a chunk's metadata as one compact line: `Metadata: k: v | k2: v2`.
+ *
+ * Merges schema-backed tenant metadata (chunk.metadata) with the free-form
+ * per-document map (chunk.additionalMetadata); the schema-backed value wins on
+ * a key conflict because it is the validated one. Both maps carry the caller's
+ * own keys — nothing is renamed, filtered, or truncated, since what to attach
+ * was the caller's decision at ingest time.
+ *
+ * This exists because the server returns metadata on every chunk and this
+ * helper used to drop all of it, so values callers had deliberately stored —
+ * dates, types, flags — were discarded one step before the model saw them.
+ * Undefined/null/empty values are skipped; keys are sorted so the same chunk
+ * always renders the same line.
+ */
+function metadataLine(chunk) {
+    const merged = {};
+    const add = chunk.additionalMetadata;
+    if (add && typeof add === "object") {
+        Object.assign(merged, add);
+    }
+    const meta = chunk.metadata;
+    if (meta && typeof meta === "object") {
+        Object.assign(merged, meta);
+    }
+    const parts = [];
+    for (const key of Object.keys(merged).sort()) {
+        const value = merged[key];
+        if (value === null || value === undefined)
+            continue;
+        const rendered = typeof value === "object" ? JSON.stringify(value) : String(value);
+        if (rendered === "")
+            continue;
+        parts.push(`${key}: ${rendered}`);
+    }
+    return parts.length > 0 ? `Metadata: ${parts.join(" | ")}` : undefined;
+}
 /**
  * Pull human-readable text out of a chunk's content field.
  *
@@ -65,6 +102,99 @@ function extractChunkText(chunkContent) {
     return s;
 }
 // ---------------------------------------------------------------------------
+// Temporal helpers
+// ---------------------------------------------------------------------------
+function epochDate(epoch) {
+    // Unix seconds (wire format of event_start/event_end) -> YYYY-MM-DD.
+    if (epoch === null || epoch === undefined || epoch === "" || epoch === 0) {
+        return undefined;
+    }
+    let e = Number(epoch);
+    if (!Number.isFinite(e) || e <= 0)
+        return undefined;
+    if (e > 1e11)
+        e /= 1000; // tolerate milliseconds
+    return new Date(e * 1000).toISOString().slice(0, 10);
+}
+function relationWhen(rel) {
+    // Best-known date for a graph relation: resolved temporal_details if the
+    // extraction dated it, else the relation's stored timestamp. Relation is a
+    // free-form map (map[string]any), so its keys stay snake_case on the wire.
+    const td = rel?.temporal_details;
+    if (typeof td === "string" && td.trim())
+        return td.trim().slice(0, 10);
+    const ts = rel?.timestamp;
+    if (ts === null || ts === undefined || ts === "")
+        return undefined;
+    return epochDate(ts) ?? String(ts).slice(0, 10);
+}
+function tripletLine(triplet, indent) {
+    let line = `${indent}[${triplet.source.name}] → ` +
+        `${triplet.relation.canonical_predicate} → ` +
+        `[${triplet.target.name}]`;
+    const when = relationWhen(triplet.relation);
+    if (when) {
+        line += ` (as of ${when})`;
+    }
+    if (triplet.relation.context) {
+        line += `: ${triplet.relation.context.trim()}`;
+    }
+    return line;
+}
+/**
+ * Render temporalDuration + temporalFacts (temporal_reasoning: true).
+ *
+ * Gated on the temporalFilter envelope: nothing renders unless the server
+ * reports applied=true, and a degraded lookup (applied=false) renders nothing
+ * rather than implying "no temporal facts exist".
+ */
+function formatTemporalPayload(data) {
+    const tf = data?.temporalFilter;
+    if (!tf || !tf.applied)
+        return undefined;
+    const lines = [];
+    const dur = data.temporalDuration;
+    if (dur && dur.days !== null && dur.days !== undefined) {
+        const approx = dur.approximate ? " (approximate)" : "";
+        lines.push(`COMPUTED DURATION: ${dur.days} days${approx} ` +
+            `(${dur.fromDate} → ${dur.toDate})`);
+    }
+    const factLines = [];
+    for (const f of data.temporalFacts ?? []) {
+        const start = epochDate(f.eventStart);
+        const end = epochDate(f.eventEnd);
+        let when = "";
+        if (start && end && end !== start) {
+            when = ` | ${start} → ${end}`;
+        }
+        else if (start) {
+            when = ` | ${start}`;
+        }
+        else if (end) {
+            when = ` | until ${end}`;
+        }
+        // current wire names first; pre-rename fallbacks keep the helper
+        // working against older servers (granularity/srcName/... era)
+        const precision = f.datePrecision ?? f.granularity;
+        if (when && (precision === "month" || precision === "year")) {
+            when += ` (~${precision})`;
+        }
+        let line = `  [${f.subject ?? f.srcName ?? ""}] → ` +
+            `${f.relation ?? f.canonicalRelation ?? ""} → ` +
+            `[${f.object ?? f.destName ?? ""}]${when}`;
+        const phrase = f.evidencePhrase ?? f.evidenceSpan;
+        if (phrase) {
+            line += ` — "${String(phrase).trim()}"`;
+        }
+        factLines.push(line);
+    }
+    if (factLines.length > 0) {
+        lines.push("Dated Facts (event dates resolved from the sources):");
+        lines.push(...factLines);
+    }
+    return lines.length > 0 ? lines.join("\n") : undefined;
+}
+// ---------------------------------------------------------------------------
 // Graph helpers
 // ---------------------------------------------------------------------------
 function buildChunkToRelationsMap(graphContext) {
@@ -76,13 +206,7 @@ function buildChunkToRelationsMap(graphContext) {
     for (const path of graphContext.chunkRelations ?? []) {
         const lines = [];
         for (const triplet of path.triplets ?? []) {
-            let line = `  [${triplet.source.name}] → ` +
-                `${triplet.relation.canonical_predicate} → ` +
-                `[${triplet.target.name}]`;
-            if (triplet.relation.context) {
-                line += `: ${triplet.relation.context.trim()}`;
-            }
-            lines.push(line);
+            lines.push(tripletLine(triplet, "  "));
         }
         if (lines.length === 0)
             continue;
@@ -122,13 +246,7 @@ function formatQueryPaths(graphContext) {
             : "";
         lines.push(`  Path ${i + 1}${scoreStr}`);
         for (const triplet of path.triplets ?? []) {
-            let line = `    [${triplet.source.name}] → ` +
-                `${triplet.relation.canonical_predicate} → ` +
-                `[${triplet.target.name}]`;
-            if (triplet.relation.context) {
-                line += `: ${triplet.relation.context.trim()}`;
-            }
-            lines.push(line);
+            lines.push(tripletLine(triplet, "    "));
         }
         if (path.combinedContext) {
             lines.push(`    Combined: ${path.combinedContext.trim()}`);
@@ -149,9 +267,12 @@ function formatChunksWithGraph(chunks, graphContext, label) {
         const chunkLines = [
             `Chunk ${i + 1}`,
             `Source: ${sourceLabel(chunk)}${scoreStr}`,
-            "",
-            extractChunkText(chunk.chunkContent),
         ];
+        const metaLine = metadataLine(chunk);
+        if (metaLine) {
+            chunkLines.push(metaLine);
+        }
+        chunkLines.push("", extractChunkText(chunk.chunkContent));
         const relations = chunkToRelations[chunk.chunkUuid] ?? [];
         if (relations.length > 0) {
             chunkLines.push("", "Graph Relations:", ...relations);
@@ -192,12 +313,9 @@ function buildString(result) {
     const queryPathsStr = formatQueryPaths(data.graphContext);
     if (queryPathsStr)
         sections.push(queryPathsStr);
-    // Synthesis renders independently of queryPaths so it isn't lost when only
-    // chunkRelations are present.
-    const synthesis = data.graphContext?.synthesisContext;
-    if (synthesis) {
-        sections.push(`Synthesis: ${synthesis.trim()}`);
-    }
+    const temporalStr = formatTemporalPayload(data);
+    if (temporalStr)
+        sections.push(temporalStr);
     return sections.length > 0
         ? sections.join("\n\n")
         : "No relevant context found.";

package/dist/helpers/index.d.ts

@@ -1 +1,2 @@
 export { buildString } from "./buildString.js";
+export { DELIVERY_ID_HEADER, EVENT_HEADER, SIGNATURE_HEADER, verifyWebhookSignature, } from "./verifyWebhook.js";

package/dist/helpers/index.js

@@ -3,6 +3,11 @@
 // hydradb-application/scripts/fern/sdk-templates/typescript/index.ts.
 // Do not edit in the SDK repo — changes will be overwritten on next regen.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildString = void 0;
+exports.verifyWebhookSignature = exports.SIGNATURE_HEADER = exports.EVENT_HEADER = exports.DELIVERY_ID_HEADER = exports.buildString = void 0;
 var buildString_js_1 = require("./buildString.js");
 Object.defineProperty(exports, "buildString", { enumerable: true, get: function () { return buildString_js_1.buildString; } });
+var verifyWebhook_js_1 = require("./verifyWebhook.js");
+Object.defineProperty(exports, "DELIVERY_ID_HEADER", { enumerable: true, get: function () { return verifyWebhook_js_1.DELIVERY_ID_HEADER; } });
+Object.defineProperty(exports, "EVENT_HEADER", { enumerable: true, get: function () { return verifyWebhook_js_1.EVENT_HEADER; } });
+Object.defineProperty(exports, "SIGNATURE_HEADER", { enumerable: true, get: function () { return verifyWebhook_js_1.SIGNATURE_HEADER; } });
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return verifyWebhook_js_1.verifyWebhookSignature; } });

package/dist/helpers/verifyWebhook.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Verification for inbound HydraDB webhook deliveries.
+ *
+ * Every signed delivery carries:
+ *
+ *     X-HydraDB-Signature: sha256=<hex>
+ *
+ * where `<hex>` is the HMAC-SHA256 of the **raw request body**, keyed by the
+ * signing secret. Signing the raw bytes is the part that is easy to get wrong:
+ * parsing the JSON and re-serialising it produces different bytes and the
+ * signature will never match. Capture the body as a Buffer before parsing it -
+ * in Express that means `express.raw({ type: "application/json" })`.
+ */
+export declare const SIGNATURE_HEADER = "X-HydraDB-Signature";
+export declare const DELIVERY_ID_HEADER = "X-HydraDB-Delivery-ID";
+export declare const EVENT_HEADER = "X-HydraDB-Event";
+/**
+ * Returns true when `signature` is a valid HydraDB signature for `rawBody`.
+ *
+ * @param secret - the signing secret configured for your webhook.
+ * @param rawBody - the request body exactly as received, unparsed.
+ * @param signature - the `X-HydraDB-Signature` header value.
+ *
+ * Comparison is constant-time. A missing secret, body, or header is treated as a
+ * failed verification rather than an error, so the call fails closed:
+ *
+ *     if (!verifyWebhookSignature(secret, rawBody, sig)) {
+ *       return res.status(401).send("Invalid signature");
+ *     }
+ */
+export declare function verifyWebhookSignature(secret: string, rawBody: Buffer | string, signature: string | undefined | null): boolean;

package/dist/helpers/verifyWebhook.js

@@ -0,0 +1,56 @@
+"use strict";
+// This file is copied into the generated SDK by CI. Source of truth is
+// hydradb-application/scripts/fern/sdk-templates/typescript/verifyWebhook.ts.
+// Do not edit in the SDK repo — changes will be overwritten on next regen.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_HEADER = exports.DELIVERY_ID_HEADER = exports.SIGNATURE_HEADER = void 0;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+/**
+ * Verification for inbound HydraDB webhook deliveries.
+ *
+ * Every signed delivery carries:
+ *
+ *     X-HydraDB-Signature: sha256=<hex>
+ *
+ * where `<hex>` is the HMAC-SHA256 of the **raw request body**, keyed by the
+ * signing secret. Signing the raw bytes is the part that is easy to get wrong:
+ * parsing the JSON and re-serialising it produces different bytes and the
+ * signature will never match. Capture the body as a Buffer before parsing it -
+ * in Express that means `express.raw({ type: "application/json" })`.
+ */
+exports.SIGNATURE_HEADER = "X-HydraDB-Signature";
+exports.DELIVERY_ID_HEADER = "X-HydraDB-Delivery-ID";
+exports.EVENT_HEADER = "X-HydraDB-Event";
+const SIGNATURE_PREFIX = "sha256=";
+/**
+ * Returns true when `signature` is a valid HydraDB signature for `rawBody`.
+ *
+ * @param secret - the signing secret configured for your webhook.
+ * @param rawBody - the request body exactly as received, unparsed.
+ * @param signature - the `X-HydraDB-Signature` header value.
+ *
+ * Comparison is constant-time. A missing secret, body, or header is treated as a
+ * failed verification rather than an error, so the call fails closed:
+ *
+ *     if (!verifyWebhookSignature(secret, rawBody, sig)) {
+ *       return res.status(401).send("Invalid signature");
+ *     }
+ */
+function verifyWebhookSignature(secret, rawBody, signature) {
+    if (!secret || !signature || rawBody == null) {
+        return false;
+    }
+    const body = typeof rawBody === "string" ? Buffer.from(rawBody) : rawBody;
+    const expected = SIGNATURE_PREFIX + node_crypto_1.default.createHmac("sha256", secret).update(body).digest("hex");
+    const expectedBuffer = Buffer.from(expected);
+    const signatureBuffer = Buffer.from(signature);
+    // timingSafeEqual throws on a length mismatch, so guard before comparing.
+    if (signatureBuffer.length !== expectedBuffer.length) {
+        return false;
+    }
+    return node_crypto_1.default.timingSafeEqual(signatureBuffer, expectedBuffer);
+}