nenavi 0.0.0 → 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Dwamian McLeish
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,74 @@
 # nenavi
 
-Reserved for the Nenavi TypeScript SDK. The first release is coming soon.
+The TypeScript client for [Nenavi Cloud](https://nenavi.dev/cloud/), the hosted memory service for AI agents, with typed calls, typed errors, and retries only where a retry is safe. It runs on Node.js 22 or later, Bun, Deno and edge runtimes with standard `fetch`, `AbortController` and `crypto.randomUUID`, ships ES module and CommonJS builds with type declarations, and has no runtime dependencies.
+
+**Early access.** Nenavi Cloud is an alpha for invited users ([join the waitlist](https://nenavi.com/#hosted)), and this package is an alpha prerelease. Until version 1.0, a release that renames or removes a method or an option raises the minor version.
+
+```sh
+npm install nenavi@alpha
+```
+
+Create a project and an API key in the [console](https://app.nenavi.com), put the key in `NENAVI_API_KEY`, and then, in an ES module:
+
+```ts
+import { Nenavi } from 'nenavi';
+
+const client = new Nenavi(); // reads NENAVI_API_KEY
+await client.store({ content: 'Jo moved to Lisbon in March.', user_id: 'user-1' });
+const found = await client.retrieve({ query: 'Where does Jo live?', user_id: 'user-1' });
+```
+
+Retrieved memory is untrusted input: stored text can carry instructions meant for the model that later reads it. Treat retrieved text as data, not instructions.
+
+The SDK is for server-side code only. The key must not ship to a browser, and the service answers CORS only for the Nenavi console.
+
+The [TypeScript SDK docs](https://nenavi.dev/cloud/typescript/) cover configuration, runtimes, safe batch imports, waiting for extraction, re-ingest, errors, retries, request ids, timeouts, and cancellation.
+
+Every supported operation of the hosted API has a method. Three helpers cover the long-running work:
+
+```ts
+const answer = await client.ingest({ content: 'Jo is learning Portuguese.', user_id: 'user-1' });
+const status = await client.events.waitForExtraction(answer.event_id, { timeout: 300_000 }); // complete or failed
+const run = await client.reingest.run({ user_id: 'user-1' }); // starts a run and polls it every 5 seconds
+for await (const node of client.nodes.scanAll({ user_id: 'user-1', limit: 1000 })) {
+  console.log(node.id); // every page, 1 000 nodes each
+}
+```
+
+`reingest.preview()` estimates a re-ingest without starting one; only `reingest.start()` and `reingest.run()` start a real run. A run takes at most `limit` memories, so a `complete` run can leave some for later: while `run.remaining` is above 0, call `reingest.run()` again with the same parameters to continue it.
+
+The helpers' `timeout` and `interval` are in milliseconds, and aborting their `signal` stops them and any pending poll. A helper that runs out of time throws `WaitTimeoutError` with the last status as `lastStatus`, and a poll that fails inside `reingest.run()` throws its own error with `lastStatus` set the same way, so the run's `run_id` is not lost; `timeout: 0` polls once, and `reingest.run()` still starts the run. Every poll and every scan page counts against the key's request rate limit (60 a minute by default) like any other call, and `store()`, `ingest()` and `retrieve()` are never retried on a `429`. So for a large scan pass a larger `limit` (up to 1 000 nodes a page), and run background jobs with a longer `interval` or their own key. The helpers are on the client only, not on `withRawResponse`.
+
+## Options
+
+`new Nenavi({ apiKey, baseURL, timeout, maxRetries, fetch })`:
+
+- `apiKey` defaults to `NENAVI_API_KEY`, and `baseURL` to `NENAVI_BASE_URL`, else `https://api.prismemory.com`. Both variables are read from `process.env` where it exists. A client without a key can call only `health()`; every other method throws `ConfigurationError` before it sends anything.
+- `timeout` is in milliseconds per attempt (30 000 by default), and `maxRetries` bounds the automatic retries (2 by default).
+- `fetch` replaces the runtime's `fetch`, for tests and unusual runtimes.
+
+Every method takes a final options argument `{ signal, timeout, maxRetries }`. Aborting `signal` stops the request and any pending retry, and the call rejects with the signal's reason, as `fetch` does. `ingestFast()` and the node `PUT` methods also take `idempotencyKey`. That reason carries no `Idempotency-Key`, so when you pass a `signal` to `ingestFast()`, pass your own `idempotencyKey` too and reuse it to retry an aborted call; a new key is a new batch, stored and metered again.
+
+On Deno, reading the two variables needs `--allow-env=NENAVI_API_KEY,NENAVI_BASE_URL`. Without it, an interactive Deno asks for the permission, and a non-interactive one treats both as unset.
+
+Request and response fields keep the API's snake_case names (`user_id`, `event_id`), and the types are generated from `sdks/openapi.json`. `client.withRawResponse` has the same methods and returns `{ status, headers, requestId, data }`.
+
+## Errors and retries
+
+Every error the SDK throws is a `NenaviError`, and every class works with `instanceof`: `APIError` and its subclasses (`AuthenticationError`, `NotFoundError`, `RateLimitError`, `QuotaExceededError`, `ServiceUnavailableError` and the others) carry `status`, `reasonCode`, `detail` and `requestId`. `APIConnectionError` and `APITimeoutError` mean no response arrived. `ResponseValidationError` means a `2xx` answer had a body the SDK could not read as the operation's type: the call may have taken effect, so read its `body` (for example the `event_id` of a `store()`) and `requestId` before calling again. `body` can hold stored memory text, and `console.error(error)` or `JSON.stringify(error)` prints it: log the message and `requestId` instead.
+
+Only `GET` methods and `ingestFast()` retry by themselves, on a `429 rate_limited` (after `Retry-After`), a `503 database_unavailable` or `lease_unavailable`, or a connection error. `store()`, `ingest()` and `retrieve()` never retry: a retried store stores the text again and counts twice against the monthly limits. `ingestFast()` sends one `Idempotency-Key` on every retry of a call. A timeout is never retried, so to retry it by hand, pass the error's `idempotencyKey`. If you wrap `ingestFast()` in your own retry loop, make one key before the first attempt and pass it on every attempt: a call without a key gets a new one, and the service stores and meters the batch again.
+
+## Development
+
+```sh
+pnpm --filter nenavi test        # builds dist/, then runs the tests
+pnpm --filter nenavi lint
+pnpm --filter nenavi type-check
+pnpm --filter nenavi build
+```
+
+- `src/generated/` holds the types generated from `sdks/openapi.json` by `openapi-typescript`, with `SPEC_VERSION` and `SPEC_SHA256`. After the snapshot changes, run `pnpm --filter nenavi generate`; `test/generated.test.ts` fails until you do.
+- `test/conformance.test.ts` runs every scenario in `sdks/conformance/` with a mock `fetch`.
+- `test/package.test.ts` loads the built package with `import` and with `require`.
+- `examples/quickstart.ts` stores and retrieves one memory with the key from `NENAVI_API_KEY` (and `NENAVI_BASE_URL` for a local service): `pnpm exec tsx examples/quickstart.ts`.

package/dist/cjs/client.d.ts

@@ -0,0 +1,328 @@
+import { Core, type Call, type ClientOptions, type IdempotentRequestOptions, type RawResponse, type RequestOptions } from './core.js';
+import type { AliasProposalReviewResponse, AliasProposalsListParams, AliasProposalsListResponse, AliasProposalsReviewParams, AnswerCitationResponse, AnswerCitationsGetParams, AnswerCitationsListParams, AnswerCitationsListResponse, AnswerCitationsRecordParams, AssertionAggregationResponse, AssertionStateResponse, AssertionsAggregateParams, AssertionsStateParams, ClaimsMarkContradictionParams, ClaimsResolveContradictionParams, ClaimsResponse, ClaimsSupersedeParams, EventNodesResponse, EventRecord, EventsRetryExtractionParams, ExtractionResponse, ExtractionStatusResponse, ExtractionsProcessParams, ExtractionsProcessResponse, FullRetrievalEvaluationResponse, GraphParams, GraphResponse, HealthResponse, IngestFastParams, IngestFastResponse, IngestParams, IngestResponse, LearningEvaluateFullRetrievalParams, LearningEvaluateParams, LearningEvaluationResponse, LearningProfilesActivateParams, LearningProfilesActiveParams, LearningProfilesCreateParams, LearningProfilesDeactivateParams, LearningProfilesGetParams, LearningProfilesHistoryParams, LearningProfilesListParams, LearningProfilesRollbackParams, MaterializationsProcessParams, MaterializationsProcessResponse, NodeChainResponse, NodeListResponse, NodeNeighborhoodResponse, NodePageResponse, NodeResponse, NodesChainParams, NodesEvaluateConditionParams, NodesListParams, NodesNeighborhoodParams, NodesProvenanceParams, NodesReinforceParams, NodesScanParams, OrganizeParams, OrganizeResponse, PlannedQuantityAggregationResponse, ProcessingStatusResponse, ProvenanceResponse, QuantitiesAggregateParams, QuantitiesAggregateTextParams, QuantityAggregationResponse, RankingProfileActiveResponse, RankingProfileDeactivateResponse, RankingProfileHistoryResponse, RankingProfileListResponse, RankingProfileResponse, RankingProfileStateResponse, RankingProfileStatusResponse, ReingestParams, ReingestPreview, ReingestRunStatus, RelevanceGetParams, RelevanceListParams, RelevanceListResponse, RelevanceRecordParams, RelevanceRecordResponse, RetrievalReceiptResponse, RetrievalsGetParams, RetrieveParams, RetrieveResponse, StatsParams, StatsResponse, StoreParams, StoreResponse, UsageResponse } from './types.js';
+/** What a method returns: the parsed body, or in the raw view its RawResponse. */
+export type APIPromise<Raw extends boolean, T> = Promise<Raw extends true ? RawResponse<T> : T>;
+declare class Resource<Raw extends boolean> {
+    protected readonly _core: Core;
+    protected readonly _raw: Raw;
+    constructor(core: Core, raw: Raw);
+    /** Build the call and send it; an error while building it rejects the promise too. */
+    protected _request<T>(build: () => Call): APIPromise<Raw, T>;
+}
+/** A helper's options (sdks/CONTRACT.md, Helpers). */
+export interface HelperOptions {
+    /**
+     * Milliseconds after which the helper stops: a deadline. Each poll's attempt gets no
+     * more than the time left (at least 1 000 milliseconds), and a retry that would wait
+     * past it is not made; a poll the deadline stops this way throws `WaitTimeoutError`
+     * too, with the poll's error as its `cause`. 0 polls once (`run()` still starts the
+     * run, with the client's own timeout); `Infinity` waits without a limit.
+     */
+    timeout?: number;
+    /** Milliseconds between polls. */
+    interval?: number;
+    /** Aborting it stops the helper and any pending poll or retry. */
+    signal?: AbortSignal | null;
+}
+/** The `/v1/events` routes. */
+export declare class Events<Raw extends boolean = false> extends Resource<Raw> {
+    /** `GET /v1/events/{event_id}`: the stored event, as the JSON object it is. */
+    get(eventId: string, options?: RequestOptions): APIPromise<Raw, EventRecord>;
+    /** `GET /v1/events/{event_id}/nodes`: the nodes derived from the event. */
+    nodes(eventId: string, options?: RequestOptions): APIPromise<Raw, EventNodesResponse>;
+    /** `GET /v1/events/{event_id}/processing-status`. */
+    processingStatus(eventId: string, options?: RequestOptions): APIPromise<Raw, ProcessingStatusResponse>;
+    /** `GET /v1/events/{event_id}/extraction`: the record, or its protected view. */
+    extraction(eventId: string, options?: RequestOptions): APIPromise<Raw, ExtractionResponse>;
+    /** `GET /v1/events/{event_id}/extraction-status`. */
+    extractionStatus(eventId: string, options?: RequestOptions): APIPromise<Raw, ExtractionStatusResponse>;
+    /** `POST /v1/events/{event_id}/retry-extraction`. Not retried automatically. */
+    retryExtraction(eventId: string, params?: EventsRetryExtractionParams, options?: RequestOptions): APIPromise<Raw, ExtractionStatusResponse>;
+}
+/** The `/v1/nodes` routes. */
+export declare class Nodes<Raw extends boolean = false> extends Resource<Raw> {
+    /** `GET /v1/nodes/{node_id}`. */
+    get(nodeId: string, options?: RequestOptions): APIPromise<Raw, NodeResponse>;
+    /** `GET /v1/nodes`: list nodes. */
+    list(params?: NodesListParams, options?: RequestOptions): APIPromise<Raw, NodeListResponse>;
+    /**
+     * `GET /v1/nodes/scan`: one page of nodes, in id order.
+     *
+     * While the page's `has_more` is true, pass its `next_cursor` as `after_id` to read the
+     * next page.
+     */
+    scan(params?: NodesScanParams, options?: RequestOptions): APIPromise<Raw, NodePageResponse>;
+    /** `GET /v1/nodes/{node_id}/provenance`: the provenance, or its protected view. */
+    provenance(nodeId: string, params?: NodesProvenanceParams, options?: RequestOptions): APIPromise<Raw, ProvenanceResponse>;
+    /** `PUT /v1/nodes/{node_id}/promote`. Not retried automatically. */
+    promote(nodeId: string, options?: IdempotentRequestOptions): APIPromise<Raw, NodeResponse>;
+    /** `PUT /v1/nodes/{node_id}/archive`. Not retried automatically. */
+    archive(nodeId: string, options?: IdempotentRequestOptions): APIPromise<Raw, NodeResponse>;
+    /**
+     * `PUT /v1/nodes/{node_id}/reinforce`. Not retried automatically.
+     *
+     * Sends a body only when `params` has a field.
+     */
+    reinforce(nodeId: string, params?: NodesReinforceParams, options?: IdempotentRequestOptions): APIPromise<Raw, NodeResponse>;
+    /** `PUT /v1/nodes/{node_id}/condition`: record a conditional claim's state. Not retried automatically. */
+    evaluateCondition(nodeId: string, params: NodesEvaluateConditionParams, options?: IdempotentRequestOptions): APIPromise<Raw, NodeResponse>;
+    /** `GET /v1/nodes/{node_id}/neighborhood`: the nodes within `max_hops` edges. */
+    neighborhood(nodeId: string, params?: NodesNeighborhoodParams, options?: RequestOptions): APIPromise<Raw, NodeNeighborhoodResponse>;
+    /** `GET /v1/nodes/{node_id}/chain`: the node's supersedence chain. */
+    chain(nodeId: string, params?: NodesChainParams, options?: RequestOptions): APIPromise<Raw, NodeChainResponse>;
+}
+/** The `/v1/reingest` routes: re-derive one end user's stored memories. */
+export declare class Reingest<Raw extends boolean = false> extends Resource<Raw> {
+    /**
+     * `POST /v1/reingest` with `dry_run: true`: count and estimate a run.
+     *
+     * Always sends `dry_run: true`, so a preview never starts a run. Not retried
+     * automatically.
+     */
+    preview(params: ReingestParams, options?: RequestOptions): APIPromise<Raw, ReingestPreview>;
+    /**
+     * `POST /v1/reingest` with `dry_run: false`: start a background run.
+     *
+     * The service answers `202` with the run's `run_id`, or `200` with `run_id: null` when
+     * nothing needs re-deriving. Each memory the run takes counts as one ingest call. A run
+     * takes at most `limit` memories, so a `complete` run can leave some for later
+     * (`remaining` above 0): sending the same request again continues it. Not retried
+     * automatically; a `409` `reingest_running` throws `ConflictError`.
+     */
+    start(params: ReingestParams, options?: RequestOptions): APIPromise<Raw, ReingestRunStatus>;
+    /** `GET /v1/reingest/{run_id}`: the run's state, counts and usage. */
+    get(runId: string, options?: RequestOptions): APIPromise<Raw, ReingestRunStatus>;
+}
+/** The claim routes: supersedences and contradictions. Not retried automatically. */
+export declare class Claims<Raw extends boolean = false> extends Resource<Raw> {
+    /** `POST /v1/supersedences`: record that one claim replaces another. */
+    supersede(params: ClaimsSupersedeParams, options?: RequestOptions): APIPromise<Raw, ClaimsResponse>;
+    /** `POST /v1/contradictions`: mark two claims as contradicting each other. */
+    markContradiction(params: ClaimsMarkContradictionParams, options?: RequestOptions): APIPromise<Raw, ClaimsResponse>;
+    /** `POST /v1/contradictions/resolve`: resolve a contradiction in favor of one claim. */
+    resolveContradiction(params: ClaimsResolveContradictionParams, options?: RequestOptions): APIPromise<Raw, ClaimsResponse>;
+}
+/** The `/v1/alias-proposals` routes: identity review. */
+export declare class AliasProposals<Raw extends boolean = false> extends Resource<Raw> {
+    /** `GET /v1/alias-proposals`: the alias proposals waiting for review. */
+    list(params?: AliasProposalsListParams, options?: RequestOptions): APIPromise<Raw, AliasProposalsListResponse>;
+    /** `POST /v1/alias-proposals/{proposal_operation_id}/review`. Not retried automatically. */
+    review(proposalOperationId: string, params: AliasProposalsReviewParams, options?: RequestOptions): APIPromise<Raw, AliasProposalReviewResponse>;
+}
+/** The `/v1/materializations` routes. */
+export declare class Materializations<Raw extends boolean = false> extends Resource<Raw> {
+    /** `POST /v1/materializations/process`: run the due materializations. Not retried automatically. */
+    process(params: MaterializationsProcessParams, options?: RequestOptions): APIPromise<Raw, MaterializationsProcessResponse>;
+}
+/** The `/v1/extractions` routes. */
+export declare class Extractions<Raw extends boolean = false> extends Resource<Raw> {
+    /** `POST /v1/extractions/process`: run the due extraction jobs. Not retried automatically. */
+    process(params: ExtractionsProcessParams, options?: RequestOptions): APIPromise<Raw, ExtractionsProcessResponse>;
+}
+/** The `/v1/assertions` routes: exact queries over assertions. Not retried automatically. */
+export declare class Assertions<Raw extends boolean = false> extends Resource<Raw> {
+    /** `POST /v1/assertions/aggregate`. */
+    aggregate(params: AssertionsAggregateParams, options?: RequestOptions): APIPromise<Raw, AssertionAggregationResponse>;
+    /** `POST /v1/assertions/state`. */
+    state(params: AssertionsStateParams, options?: RequestOptions): APIPromise<Raw, AssertionStateResponse>;
+}
+/** The `/v1/quantities` routes: exact queries over quantities. Not retried automatically. */
+export declare class Quantities<Raw extends boolean = false> extends Resource<Raw> {
+    /** `POST /v1/quantities/aggregate`. */
+    aggregate(params: QuantitiesAggregateParams, options?: RequestOptions): APIPromise<Raw, QuantityAggregationResponse>;
+    /** `POST /v1/quantities/aggregate-text`: plan and run an aggregation from a question. */
+    aggregateText(params: QuantitiesAggregateTextParams, options?: RequestOptions): APIPromise<Raw, PlannedQuantityAggregationResponse>;
+}
+/** The `/v1/retrievals` routes: retrieval receipts. */
+export declare class Retrievals<Raw extends boolean = false> extends Resource<Raw> {
+    /** `GET /v1/retrievals/{request_id}`: the receipt, or one of its protected views. */
+    get(requestId: string, params?: RetrievalsGetParams, options?: RequestOptions): APIPromise<Raw, RetrievalReceiptResponse>;
+}
+/** The `/v1/relevance` routes: relevance feedback. */
+export declare class Relevance<Raw extends boolean = false> extends Resource<Raw> {
+    /** `POST /v1/relevance`: record feedback on a retrieved memory. Not retried automatically. */
+    record(params: RelevanceRecordParams, options?: RequestOptions): APIPromise<Raw, RelevanceRecordResponse>;
+    /** `GET /v1/relevance`: the recorded feedback. */
+    list(params?: RelevanceListParams, options?: RequestOptions): APIPromise<Raw, RelevanceListResponse>;
+    /** `GET /v1/relevance/{feedback_id}`. */
+    get(feedbackId: string, params?: RelevanceGetParams, options?: RequestOptions): APIPromise<Raw, RelevanceRecordResponse>;
+}
+/** The `/v1/answer-citations` routes: which memories an answer cited. */
+export declare class AnswerCitations<Raw extends boolean = false> extends Resource<Raw> {
+    /** `POST /v1/answer-citations`: record an answer's citations. Not retried automatically. */
+    record(params: AnswerCitationsRecordParams, options?: RequestOptions): APIPromise<Raw, AnswerCitationResponse>;
+    /** `GET /v1/answer-citations`: the recorded citations, each a record or its protected view. */
+    list(params?: AnswerCitationsListParams, options?: RequestOptions): APIPromise<Raw, AnswerCitationsListResponse>;
+    /** `GET /v1/answer-citations/{citation_id}`: the record, or its protected view. */
+    get(citationId: string, params?: AnswerCitationsGetParams, options?: RequestOptions): APIPromise<Raw, AnswerCitationResponse>;
+}
+/** The `/v1/learning/profiles` routes: ranking profiles. */
+export declare class LearningProfiles<Raw extends boolean = false> extends Resource<Raw> {
+    /** `GET /v1/learning/profiles`. */
+    list(params?: LearningProfilesListParams, options?: RequestOptions): APIPromise<Raw, RankingProfileListResponse>;
+    /** `POST /v1/learning/profiles`: create a profile. Not retried automatically. */
+    create(params: LearningProfilesCreateParams, options?: RequestOptions): APIPromise<Raw, RankingProfileResponse>;
+    /** `GET /v1/learning/profiles/{profile_id}`: the profile and its status. */
+    get(profileId: string, params?: LearningProfilesGetParams, options?: RequestOptions): APIPromise<Raw, RankingProfileStatusResponse>;
+    /** `GET /v1/learning/profiles/active`: the active profile, or null when none is. */
+    active(params?: LearningProfilesActiveParams, options?: RequestOptions): APIPromise<Raw, RankingProfileActiveResponse>;
+    /** `GET /v1/learning/profiles/history`: the activation history. */
+    history(params?: LearningProfilesHistoryParams, options?: RequestOptions): APIPromise<Raw, RankingProfileHistoryResponse>;
+    /** `POST /v1/learning/profiles/{profile_id}/activate`. Not retried automatically. */
+    activate(profileId: string, params: LearningProfilesActivateParams, options?: RequestOptions): APIPromise<Raw, RankingProfileStateResponse>;
+    /** `POST /v1/learning/profiles/deactivate`: null when no profile was active. Not retried automatically. */
+    deactivate(params: LearningProfilesDeactivateParams, options?: RequestOptions): APIPromise<Raw, RankingProfileDeactivateResponse>;
+    /** `POST /v1/learning/profiles/rollback`. Not retried automatically. */
+    rollback(params: LearningProfilesRollbackParams, options?: RequestOptions): APIPromise<Raw, RankingProfileStateResponse>;
+}
+/** The `/v1/learning` routes: offline evaluation and ranking profiles. */
+export declare class Learning<Raw extends boolean = false> extends Resource<Raw> {
+    readonly profiles: LearningProfiles<Raw>;
+    constructor(core: Core, raw: Raw);
+    /** `POST /v1/learning/evaluate`. Not retried automatically. */
+    evaluate(params: LearningEvaluateParams, options?: RequestOptions): APIPromise<Raw, LearningEvaluationResponse>;
+    /** `POST /v1/learning/evaluate-full-retrieval`. Not retried automatically. */
+    evaluateFullRetrieval(params: LearningEvaluateFullRetrievalParams, options?: RequestOptions): APIPromise<Raw, FullRetrievalEvaluationResponse>;
+}
+/** `client.events`: the event routes and `waitForExtraction()`. */
+export declare class EventsWithHelpers extends Events<false> {
+    /**
+     * Poll the event's extraction status until it is no longer `pending` or `running`.
+     *
+     * Polls `GET /v1/events/{event_id}/extraction-status` at once and then every
+     * `interval` milliseconds (2 000), and returns the first status that is not `pending`
+     * or `running`: `complete`, `failed` (returned, not thrown), or a status this SDK does
+     * not know yet. When `timeout` milliseconds (300 000) run out first, throws
+     * `WaitTimeoutError` with the last status as `lastStatus`; `timeout` is a deadline that
+     * also bounds each poll and its retries (see `HelperOptions`). Aborting `signal` stops
+     * the helper and any pending poll or retry. Each poll is an ordinary call, with the
+     * client's retries and errors, and counts against the key's request rate limit like any
+     * other call, so many waits at once can slow the key's other calls. A job can stay
+     * `pending` until the next batch flush; `extractions.process()` runs the due jobs.
+     */
+    waitForExtraction(eventId: string, options?: HelperOptions): Promise<ExtractionStatusResponse>;
+}
+/** `client.nodes`: the node routes and `scanAll()`. */
+export declare class NodesWithHelpers extends Nodes<false> {
+    /**
+     * Yield every node `scan()` reaches, one page after another.
+     *
+     * While a page's `has_more` is true, sends its `next_cursor` as the next `after_id`,
+     * with the other parameters unchanged; `limit` is the page size. Each page is an
+     * ordinary `scan()` call with `options`, sent as soon as the previous page is read, and
+     * counts against the key's request rate limit: a large `limit` (up to 1 000) needs fewer
+     * pages. A page whose `has_more` is true without a new `next_cursor` throws
+     * `NenaviError`, so a scan never ends early without saying so.
+     *
+     * @example
+     * for await (const node of client.nodes.scanAll({ user_id: 'user-1', limit: 1000 })) {
+     *   console.log(node.id);
+     * }
+     */
+    scanAll(params?: NodesScanParams, options?: RequestOptions): AsyncGenerator<NodeResponse, void, undefined>;
+}
+/** `client.reingest`: the re-ingest routes and `run()`. */
+export declare class ReingestWithHelpers extends Reingest<false> {
+    /**
+     * Start a re-ingest run and poll it until its `state` is final.
+     *
+     * Sends `start()` (`dry_run: false`), then polls `get()` every `interval` milliseconds
+     * (5 000) and returns the first status whose `state` is not `pending` or `running`:
+     * `complete`, `failed` (returned, not thrown), or a state this SDK does not know yet.
+     * When nothing needs re-deriving, the service's `200` answer is returned as it is. A
+     * `409` `reingest_running` throws `ConflictError`. When `timeout` milliseconds
+     * (3 600 000) run out first, throws `WaitTimeoutError` with the last status as
+     * `lastStatus`; the run itself goes on. `timeout` is a deadline that also bounds each
+     * poll and its retries (see `HelperOptions`); it never prevents or cuts short the start,
+     * which has the client's own timeout. Aborting `signal` stops the helper and any pending
+     * poll, not the run. A poll that fails throws that call's error while the run goes on,
+     * with the last status read before it as `lastStatus`: its `run_id` lets the caller go
+     * on polling with `get()` instead of calling `run()` again, which throws `ConflictError`
+     * (`reingest_running`) until the run ends.
+     *
+     * A run takes at most `limit` memories, so a `complete` run can leave some for later
+     * (`remaining` above 0): calling `run()` again with the same parameters continues it.
+     */
+    run(params: ReingestParams, options?: HelperOptions): Promise<ReingestRunStatus>;
+}
+/** The operations, in the parsed form (`Nenavi`) or the raw form (`withRawResponse`). */
+export declare class NenaviMethods<Raw extends boolean = false> extends Resource<Raw> {
+    readonly events: Events<Raw>;
+    readonly nodes: Nodes<Raw>;
+    readonly reingest: Reingest<Raw>;
+    readonly claims: Claims<Raw>;
+    readonly aliasProposals: AliasProposals<Raw>;
+    readonly materializations: Materializations<Raw>;
+    readonly extractions: Extractions<Raw>;
+    readonly assertions: Assertions<Raw>;
+    readonly quantities: Quantities<Raw>;
+    readonly retrievals: Retrievals<Raw>;
+    readonly relevance: Relevance<Raw>;
+    readonly answerCitations: AnswerCitations<Raw>;
+    readonly learning: Learning<Raw>;
+    constructor(core: Core, raw: Raw);
+    /** `GET /v1/health`. Sends no key, and works on a client built without one. */
+    health(options?: RequestOptions): APIPromise<Raw, HealthResponse>;
+    /** `GET /v1/usage`: this month's usage and the project's quota. */
+    usage(options?: RequestOptions): APIPromise<Raw, UsageResponse>;
+    /** `GET /v1/stats`: event and node counts. */
+    stats(params?: StatsParams, options?: RequestOptions): APIPromise<Raw, StatsResponse>;
+    /**
+     * `POST /v1/store`: store one memory.
+     *
+     * Never retried automatically: a retry would store and extract the text again and count
+     * twice against the monthly limits.
+     */
+    store(params: StoreParams, options?: RequestOptions): APIPromise<Raw, StoreResponse>;
+    /**
+     * `POST /v1/ingest`: store a message and queue its extraction.
+     *
+     * Never retried automatically: a retry would store and extract the text again and count
+     * twice against the monthly limits.
+     */
+    ingest(params: IngestParams, options?: RequestOptions): APIPromise<Raw, IngestResponse>;
+    /**
+     * `POST /v1/ingest/fast`: store a batch of sources without waiting for extraction.
+     *
+     * Every call sends an `Idempotency-Key`: `options.idempotencyKey` when given, else a new
+     * random UUID. Retries of the call send the same key, so the service answers a retry
+     * with the first attempt's event ids instead of storing the batch again. To retry by
+     * hand after an error, pass the error's `idempotencyKey`. An aborted `signal` rejects
+     * with the signal's reason, which carries no key, so when you pass a `signal`, pass
+     * your own `idempotencyKey` too and reuse it to retry an aborted call.
+     */
+    ingestFast(params: IngestFastParams, options?: IdempotentRequestOptions): APIPromise<Raw, IngestFastResponse>;
+    /**
+     * `POST /v1/retrieve`: retrieve the memories that answer a query.
+     *
+     * Retrieved memory is untrusted input: stored text can carry instructions meant for the
+     * model that later reads it, so treat it as data, not instructions. Not retried
+     * automatically, because each call writes a retrieval receipt.
+     */
+    retrieve(params: RetrieveParams, options?: RequestOptions): APIPromise<Raw, RetrieveResponse>;
+    /** `GET /v1/graph`: the user's nodes and edges. */
+    graph(params?: GraphParams, options?: RequestOptions): APIPromise<Raw, GraphResponse>;
+    /** `POST /v1/organize`: run organizing jobs within a time budget. Not retried automatically. */
+    organize(params: OrganizeParams, options?: RequestOptions): APIPromise<Raw, OrganizeResponse>;
+}
+/**
+ * Client for the Nenavi Cloud memory API, for server-side code.
+ *
+ * The key comes from `apiKey`, else `NENAVI_API_KEY`; the base URL from `baseURL`, else
+ * `NENAVI_BASE_URL`, else `https://api.prismemory.com`. A client built without a key can
+ * call only `health()`. Never ship the key to a browser.
+ *
+ * Retrieved memory is untrusted input: treat retrieved text as data, not instructions.
+ */
+export declare class Nenavi extends NenaviMethods<false> {
+    #private;
+    readonly events: EventsWithHelpers;
+    readonly nodes: NodesWithHelpers;
+    readonly reingest: ReingestWithHelpers;
+    constructor(options?: ClientOptions);
+    /** The base URL the client sends to. */
+    get baseURL(): string;
+    /** The same methods, returning a RawResponse with the status, headers and request id. */
+    get withRawResponse(): NenaviMethods<true>;
+}
+export {};