@org-quicko/silo-client 1.0.0

package/dist/request-options.d.cts

@@ -0,0 +1,9 @@
+/**
+ * The one cancellation convention on every call: the last parameter of
+ * every method in the client. A per-call value wins over the client's own
+ * default timeout.
+ */
+export interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMilliseconds?: number;
+}

package/dist/request-options.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The one cancellation convention on every call: the last parameter of
+ * every method in the client. A per-call value wins over the client's own
+ * default timeout.
+ */
+export interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMilliseconds?: number;
+}

package/dist/scope/delete-options.d.cts

@@ -0,0 +1,9 @@
+import type { RequestOptions } from "../request-options.cjs";
+/**
+ * `delete()`'s options across projects, environments, collections and
+ * entries. `force` bypasses the server's "not empty" or "still referenced"
+ * refusal.
+ */
+export interface DeleteOptions extends RequestOptions {
+    force?: boolean;
+}

package/dist/scope/delete-options.d.ts

@@ -0,0 +1,9 @@
+import type { RequestOptions } from "../request-options.js";
+/**
+ * `delete()`'s options across projects, environments, collections and
+ * entries. `force` bypasses the server's "not empty" or "still referenced"
+ * refusal.
+ */
+export interface DeleteOptions extends RequestOptions {
+    force?: boolean;
+}

package/dist/scope/environment-handle.d.cts

@@ -0,0 +1,29 @@
+import { CollectionHandle } from "../collections/collection-handle.cjs";
+import { Collections } from "../collections/collections.cjs";
+import type { CollectionDefinition } from "../collections/collection-definition.cjs";
+import type { RequestOptions } from "../request-options.cjs";
+import type { SearchPage } from "../search/search-page.cjs";
+import type { SearchQuery } from "../search/search-query.cjs";
+import { EnvironmentVariables } from "../variables/environment-variables.cjs";
+import type { DeleteOptions } from "./delete-options.cjs";
+import type { RenameOptions } from "./rename-options.cjs";
+import { RenameReport } from "./rename-report.cjs";
+import type { ScopeReference } from "./scope-reference.cjs";
+/**
+ * One environment, addressed by the name it was built with. Immutable, for
+ * the reason `ProjectHandle` is.
+ */
+export declare class EnvironmentHandle {
+    private readonly scope;
+    readonly name: string;
+    readonly project: string;
+    readonly collections: Collections;
+    readonly variables: EnvironmentVariables;
+    constructor(scope: ScopeReference);
+    collection<Fields = Record<string, unknown>>(name: string): CollectionHandle<Fields>;
+    /** Every schema in the scope, in one request. */
+    schemas(options?: RequestOptions): Promise<CollectionDefinition[]>;
+    search(query: SearchQuery, options?: RequestOptions): Promise<SearchPage>;
+    rename(name: string, options?: RenameOptions): Promise<RenameReport>;
+    delete(options?: DeleteOptions): Promise<void>;
+}

package/dist/scope/environment-handle.d.ts

@@ -0,0 +1,29 @@
+import { CollectionHandle } from "../collections/collection-handle.js";
+import { Collections } from "../collections/collections.js";
+import type { CollectionDefinition } from "../collections/collection-definition.js";
+import type { RequestOptions } from "../request-options.js";
+import type { SearchPage } from "../search/search-page.js";
+import type { SearchQuery } from "../search/search-query.js";
+import { EnvironmentVariables } from "../variables/environment-variables.js";
+import type { DeleteOptions } from "./delete-options.js";
+import type { RenameOptions } from "./rename-options.js";
+import { RenameReport } from "./rename-report.js";
+import type { ScopeReference } from "./scope-reference.js";
+/**
+ * One environment, addressed by the name it was built with. Immutable, for
+ * the reason `ProjectHandle` is.
+ */
+export declare class EnvironmentHandle {
+    private readonly scope;
+    readonly name: string;
+    readonly project: string;
+    readonly collections: Collections;
+    readonly variables: EnvironmentVariables;
+    constructor(scope: ScopeReference);
+    collection<Fields = Record<string, unknown>>(name: string): CollectionHandle<Fields>;
+    /** Every schema in the scope, in one request. */
+    schemas(options?: RequestOptions): Promise<CollectionDefinition[]>;
+    search(query: SearchQuery, options?: RequestOptions): Promise<SearchPage>;
+    rename(name: string, options?: RenameOptions): Promise<RenameReport>;
+    delete(options?: DeleteOptions): Promise<void>;
+}

package/dist/scope/environment.d.cts

@@ -0,0 +1,8 @@
+/**
+ * An environment as the listing and create routes answer it. `id` is the
+ * record's ULID and never changes; `name` is what every path addresses.
+ */
+export interface Environment {
+    readonly id: string;
+    readonly name: string;
+}

package/dist/scope/environment.d.ts

@@ -0,0 +1,8 @@
+/**
+ * An environment as the listing and create routes answer it. `id` is the
+ * record's ULID and never changes; `name` is what every path addresses.
+ */
+export interface Environment {
+    readonly id: string;
+    readonly name: string;
+}

package/dist/scope/environments.d.cts

@@ -0,0 +1,11 @@
+import type { RequestOptions } from "../request-options.cjs";
+import type { Transport } from "../transport/transport.cjs";
+import type { Environment } from "./environment.cjs";
+/** Environments within one project: `list` and `create`. */
+export declare class Environments {
+    private readonly transport;
+    private readonly project;
+    constructor(transport: Transport, project: string);
+    list(options?: RequestOptions): Promise<Environment[]>;
+    create(name: string, options?: RequestOptions): Promise<Environment>;
+}

package/dist/scope/environments.d.ts

@@ -0,0 +1,11 @@
+import type { RequestOptions } from "../request-options.js";
+import type { Transport } from "../transport/transport.js";
+import type { Environment } from "./environment.js";
+/** Environments within one project: `list` and `create`. */
+export declare class Environments {
+    private readonly transport;
+    private readonly project;
+    constructor(transport: Transport, project: string);
+    list(options?: RequestOptions): Promise<Environment[]>;
+    create(name: string, options?: RequestOptions): Promise<Environment>;
+}

package/dist/scope/project-handle.d.cts

@@ -0,0 +1,22 @@
+import type { Transport } from "../transport/transport.cjs";
+import { ProjectVariables } from "../variables/project-variables.cjs";
+import type { DeleteOptions } from "./delete-options.cjs";
+import { EnvironmentHandle } from "./environment-handle.cjs";
+import { Environments } from "./environments.cjs";
+import type { RenameOptions } from "./rename-options.cjs";
+import { RenameReport } from "./rename-report.cjs";
+/**
+ * One project, addressed by the name it was built with. Immutable: after a
+ * rename this handle still addresses the name that no longer exists, and its
+ * next call is a `NotFoundError`. Build a new handle for the new name.
+ */
+export declare class ProjectHandle {
+    private readonly transport;
+    readonly name: string;
+    readonly environments: Environments;
+    readonly variables: ProjectVariables;
+    constructor(transport: Transport, name: string);
+    environment(name: string): EnvironmentHandle;
+    rename(name: string, options?: RenameOptions): Promise<RenameReport>;
+    delete(options?: DeleteOptions): Promise<void>;
+}

package/dist/scope/project-handle.d.ts

@@ -0,0 +1,22 @@
+import type { Transport } from "../transport/transport.js";
+import { ProjectVariables } from "../variables/project-variables.js";
+import type { DeleteOptions } from "./delete-options.js";
+import { EnvironmentHandle } from "./environment-handle.js";
+import { Environments } from "./environments.js";
+import type { RenameOptions } from "./rename-options.js";
+import { RenameReport } from "./rename-report.js";
+/**
+ * One project, addressed by the name it was built with. Immutable: after a
+ * rename this handle still addresses the name that no longer exists, and its
+ * next call is a `NotFoundError`. Build a new handle for the new name.
+ */
+export declare class ProjectHandle {
+    private readonly transport;
+    readonly name: string;
+    readonly environments: Environments;
+    readonly variables: ProjectVariables;
+    constructor(transport: Transport, name: string);
+    environment(name: string): EnvironmentHandle;
+    rename(name: string, options?: RenameOptions): Promise<RenameReport>;
+    delete(options?: DeleteOptions): Promise<void>;
+}

package/dist/scope/project.d.cts

@@ -0,0 +1,8 @@
+/**
+ * A project as the listing and create routes answer it. `id` is the record's
+ * ULID and never changes; `name` is what every path addresses.
+ */
+export interface Project {
+    readonly id: string;
+    readonly name: string;
+}

package/dist/scope/project.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A project as the listing and create routes answer it. `id` is the record's
+ * ULID and never changes; `name` is what every path addresses.
+ */
+export interface Project {
+    readonly id: string;
+    readonly name: string;
+}

package/dist/scope/projects.d.cts

@@ -0,0 +1,10 @@
+import type { RequestOptions } from "../request-options.cjs";
+import type { Transport } from "../transport/transport.cjs";
+import type { Project } from "./project.cjs";
+/** Projects at the instance root: `list` and `create`. */
+export declare class Projects {
+    private readonly transport;
+    constructor(transport: Transport);
+    list(options?: RequestOptions): Promise<Project[]>;
+    create(name: string, options?: RequestOptions): Promise<Project>;
+}

package/dist/scope/projects.d.ts

@@ -0,0 +1,10 @@
+import type { RequestOptions } from "../request-options.js";
+import type { Transport } from "../transport/transport.js";
+import type { Project } from "./project.js";
+/** Projects at the instance root: `list` and `create`. */
+export declare class Projects {
+    private readonly transport;
+    constructor(transport: Transport);
+    list(options?: RequestOptions): Promise<Project[]>;
+    create(name: string, options?: RequestOptions): Promise<Project>;
+}

package/dist/scope/rename-options.d.cts

@@ -0,0 +1,10 @@
+import type { RequestOptions } from "../request-options.cjs";
+/**
+ * `rename()`'s options across projects, environments and collections.
+ * `expectedId` binds the call to the record a caller already read — from a
+ * dry run's report, from `list()`, or supplied directly.
+ */
+export interface RenameOptions extends RequestOptions {
+    expectedId?: string;
+    dryRun?: boolean;
+}

package/dist/scope/rename-options.d.ts

@@ -0,0 +1,10 @@
+import type { RequestOptions } from "../request-options.js";
+/**
+ * `rename()`'s options across projects, environments and collections.
+ * `expectedId` binds the call to the record a caller already read — from a
+ * dry run's report, from `list()`, or supplied directly.
+ */
+export interface RenameOptions extends RequestOptions {
+    expectedId?: string;
+    dryRun?: boolean;
+}

package/dist/scope/rename-report.d.cts

@@ -0,0 +1,21 @@
+/** The wire's rename preview/result shape, exactly as the server answers it. */
+export interface RenamePreviewPayload {
+    id: string;
+    from: string;
+    to: string;
+    rewritten_claims: string[];
+    pattern_affected_claims: string[];
+}
+/**
+ * What a rename did, or would do. `id` is the record the rename acted
+ * on — pass it as `expectedId` to turn a dry run's report into the real call.
+ */
+export declare class RenameReport {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+    readonly rewrittenClaims: readonly string[];
+    readonly patternAffectedClaims: readonly string[];
+    private constructor();
+    static fromWire(payload: RenamePreviewPayload): RenameReport;
+}

package/dist/scope/rename-report.d.ts

@@ -0,0 +1,21 @@
+/** The wire's rename preview/result shape, exactly as the server answers it. */
+export interface RenamePreviewPayload {
+    id: string;
+    from: string;
+    to: string;
+    rewritten_claims: string[];
+    pattern_affected_claims: string[];
+}
+/**
+ * What a rename did, or would do. `id` is the record the rename acted
+ * on — pass it as `expectedId` to turn a dry run's report into the real call.
+ */
+export declare class RenameReport {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+    readonly rewrittenClaims: readonly string[];
+    readonly patternAffectedClaims: readonly string[];
+    private constructor();
+    static fromWire(payload: RenamePreviewPayload): RenameReport;
+}

package/dist/scope/scope-reference.d.cts

@@ -0,0 +1,12 @@
+import type { Transport } from "../transport/transport.cjs";
+/**
+ * The transport plus the project and environment names a handle needs to
+ * build its own paths — what `EnvironmentHandle` hands to everything it
+ * constructs, so none of them repeats the same three constructor parameters.
+ */
+export declare class ScopeReference {
+    readonly transport: Transport;
+    readonly project: string;
+    readonly environment: string;
+    constructor(transport: Transport, project: string, environment: string);
+}

package/dist/scope/scope-reference.d.ts

@@ -0,0 +1,12 @@
+import type { Transport } from "../transport/transport.js";
+/**
+ * The transport plus the project and environment names a handle needs to
+ * build its own paths — what `EnvironmentHandle` hands to everything it
+ * constructs, so none of them repeats the same three constructor parameters.
+ */
+export declare class ScopeReference {
+    readonly transport: Transport;
+    readonly project: string;
+    readonly environment: string;
+    constructor(transport: Transport, project: string, environment: string);
+}

package/dist/search/search-engine.d.cts

@@ -0,0 +1,3 @@
+/** Which engine answered a search: the portable in-process scan, or SQLite
+ *  FTS5 where the build has it. */
+export type SearchEngine = "fts5" | "scan";

package/dist/search/search-engine.d.ts

@@ -0,0 +1,3 @@
+/** Which engine answered a search: the portable in-process scan, or SQLite
+ *  FTS5 where the build has it. */
+export type SearchEngine = "fts5" | "scan";

package/dist/search/search-hit.d.cts

@@ -0,0 +1,18 @@
+import type { ResolvedEntry } from "../entries/resolved-entry.cjs";
+import type { SearchSnippet } from "./search-snippet.cjs";
+/**
+ * One result. The location sits on the hit rather than on the entry, which is
+ * what lets a caller link to a result found outside the scope on screen, and
+ * `environment` is mapped from the wire's `env`.
+ *
+ * The entry is always a `ResolvedEntry`: a result is not addressed to one
+ * typed collection, so there is no `Fields` to give it, and it is not meant to
+ * be edited from here — re-read through `collection.edit()` for that.
+ */
+export interface SearchHit {
+    readonly project: string;
+    readonly environment: string;
+    readonly collection: string;
+    readonly entry: ResolvedEntry<unknown>;
+    readonly snippets: readonly SearchSnippet[];
+}

package/dist/search/search-hit.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedEntry } from "../entries/resolved-entry.js";
+import type { SearchSnippet } from "./search-snippet.js";
+/**
+ * One result. The location sits on the hit rather than on the entry, which is
+ * what lets a caller link to a result found outside the scope on screen, and
+ * `environment` is mapped from the wire's `env`.
+ *
+ * The entry is always a `ResolvedEntry`: a result is not addressed to one
+ * typed collection, so there is no `Fields` to give it, and it is not meant to
+ * be edited from here — re-read through `collection.edit()` for that.
+ */
+export interface SearchHit {
+    readonly project: string;
+    readonly environment: string;
+    readonly collection: string;
+    readonly entry: ResolvedEntry<unknown>;
+    readonly snippets: readonly SearchSnippet[];
+}

package/dist/search/search-page.d.cts

@@ -0,0 +1,19 @@
+import { Page } from "../pagination/page.cjs";
+import type { PageWindow } from "../pagination/page-window.cjs";
+import type { SearchEngine } from "./search-engine.cjs";
+import type { SearchHit } from "./search-hit.cjs";
+/** Loads the page at `window`, keeping whatever query produced this page. */
+export type SearchPageLoader = (window: PageWindow) => Promise<SearchPage>;
+/**
+ * One page of search results. `pageCount` is `null` when
+ * `truncated` — the base `Page` class already does that; this only adds
+ * `hits` and `engine`.
+ */
+export declare class SearchPage extends Page<SearchHit> {
+    private readonly loader;
+    readonly engine: SearchEngine;
+    constructor(rows: readonly SearchHit[], total: number, window: PageWindow, truncated: boolean, engine: SearchEngine, loader: SearchPageLoader);
+    get hits(): readonly SearchHit[];
+    next(): Promise<SearchPage | null>;
+    previous(): Promise<SearchPage | null>;
+}

package/dist/search/search-page.d.ts

@@ -0,0 +1,19 @@
+import { Page } from "../pagination/page.js";
+import type { PageWindow } from "../pagination/page-window.js";
+import type { SearchEngine } from "./search-engine.js";
+import type { SearchHit } from "./search-hit.js";
+/** Loads the page at `window`, keeping whatever query produced this page. */
+export type SearchPageLoader = (window: PageWindow) => Promise<SearchPage>;
+/**
+ * One page of search results. `pageCount` is `null` when
+ * `truncated` — the base `Page` class already does that; this only adds
+ * `hits` and `engine`.
+ */
+export declare class SearchPage extends Page<SearchHit> {
+    private readonly loader;
+    readonly engine: SearchEngine;
+    constructor(rows: readonly SearchHit[], total: number, window: PageWindow, truncated: boolean, engine: SearchEngine, loader: SearchPageLoader);
+    get hits(): readonly SearchHit[];
+    next(): Promise<SearchPage | null>;
+    previous(): Promise<SearchPage | null>;
+}

package/dist/search/search-query.d.cts

@@ -0,0 +1,11 @@
+import type { FilterExpression } from "../query/filter-expression.cjs";
+import type { SortTerm } from "../query/sort-term.cjs";
+/** Everything a search accepts, all optional. `query` maps to the wire's
+ *  `q`; omitting `sort` ranks by relevance instead. */
+export interface SearchQuery {
+    query?: string;
+    where?: FilterExpression;
+    sort?: SortTerm | string;
+    limit?: number;
+    offset?: number;
+}

package/dist/search/search-query.d.ts

@@ -0,0 +1,11 @@
+import type { FilterExpression } from "../query/filter-expression.js";
+import type { SortTerm } from "../query/sort-term.js";
+/** Everything a search accepts, all optional. `query` maps to the wire's
+ *  `q`; omitting `sort` ranks by relevance instead. */
+export interface SearchQuery {
+    query?: string;
+    where?: FilterExpression;
+    sort?: SortTerm | string;
+    limit?: number;
+    offset?: number;
+}

package/dist/search/search-reach.d.cts

@@ -0,0 +1,12 @@
+/**
+ * How far one search reaches: one collection, one environment, or the
+ * whole instance. The reach is the receiver a caller calls `search()` on, so
+ * a forgotten argument cannot widen a search past what was asked for.
+ */
+export declare class SearchReach {
+    readonly path: string;
+    private constructor();
+    static collection(project: string, environment: string, name: string): SearchReach;
+    static environment(project: string, environment: string): SearchReach;
+    static instance(): SearchReach;
+}

package/dist/search/search-reach.d.ts

@@ -0,0 +1,12 @@
+/**
+ * How far one search reaches: one collection, one environment, or the
+ * whole instance. The reach is the receiver a caller calls `search()` on, so
+ * a forgotten argument cannot widen a search past what was asked for.
+ */
+export declare class SearchReach {
+    readonly path: string;
+    private constructor();
+    static collection(project: string, environment: string, name: string): SearchReach;
+    static environment(project: string, environment: string): SearchReach;
+    static instance(): SearchReach;
+}

package/dist/search/search-snippet.d.cts

@@ -0,0 +1,8 @@
+/** Where a match was found, split into three plain strings rather than one
+ *  with markers in it: the fragment is `before + match + after`. */
+export interface SearchSnippet {
+    readonly path: string;
+    readonly before: string;
+    readonly match: string;
+    readonly after: string;
+}

package/dist/search/search-snippet.d.ts

@@ -0,0 +1,8 @@
+/** Where a match was found, split into three plain strings rather than one
+ *  with markers in it: the fragment is `before + match + after`. */
+export interface SearchSnippet {
+    readonly path: string;
+    readonly before: string;
+    readonly match: string;
+    readonly after: string;
+}

package/dist/search/search.d.cts

@@ -0,0 +1,18 @@
+import type { RequestOptions } from "../request-options.cjs";
+import type { Transport } from "../transport/transport.cjs";
+import { SearchPage } from "./search-page.cjs";
+import type { SearchQuery } from "./search-query.cjs";
+import type { SearchReach } from "./search-reach.cjs";
+/**
+ * Search, bound to one reach: a collection, an environment, or the
+ * whole instance. `CollectionHandle.search`, `EnvironmentHandle.search` and
+ * the root `Silo.search` each construct one of these against their own
+ * reach rather than exposing a reach as an argument that could be forgotten.
+ */
+export declare class Search {
+    private readonly transport;
+    private readonly reach;
+    constructor(transport: Transport, reach: SearchReach);
+    run(query: SearchQuery, options?: RequestOptions): Promise<SearchPage>;
+    private toHit;
+}

package/dist/search/search.d.ts

@@ -0,0 +1,18 @@
+import type { RequestOptions } from "../request-options.js";
+import type { Transport } from "../transport/transport.js";
+import { SearchPage } from "./search-page.js";
+import type { SearchQuery } from "./search-query.js";
+import type { SearchReach } from "./search-reach.js";
+/**
+ * Search, bound to one reach: a collection, an environment, or the
+ * whole instance. `CollectionHandle.search`, `EnvironmentHandle.search` and
+ * the root `Silo.search` each construct one of these against their own
+ * reach rather than exposing a reach as an argument that could be forgotten.
+ */
+export declare class Search {
+    private readonly transport;
+    private readonly reach;
+    constructor(transport: Transport, reach: SearchReach);
+    run(query: SearchQuery, options?: RequestOptions): Promise<SearchPage>;
+    private toHit;
+}

package/dist/silo-options.d.cts

@@ -0,0 +1,12 @@
+import type { FetchFunction } from "./transport/fetch-function.cjs";
+/**
+ * Everything `new Silo(...)` accepts. Only `url` is required: a key is
+ * optional because anonymous reads are legal.
+ */
+export interface SiloOptions {
+    url: string;
+    key?: string;
+    timeoutMilliseconds?: number;
+    headers?: Record<string, string>;
+    fetch?: FetchFunction;
+}

package/dist/silo-options.d.ts

@@ -0,0 +1,12 @@
+import type { FetchFunction } from "./transport/fetch-function.js";
+/**
+ * Everything `new Silo(...)` accepts. Only `url` is required: a key is
+ * optional because anonymous reads are legal.
+ */
+export interface SiloOptions {
+    url: string;
+    key?: string;
+    timeoutMilliseconds?: number;
+    headers?: Record<string, string>;
+    fetch?: FetchFunction;
+}

package/dist/silo.d.cts

@@ -0,0 +1,42 @@
+import type { HealthReport } from "./instance/health-report.cjs";
+import { Media } from "./media/media.cjs";
+import type { RequestOptions } from "./request-options.cjs";
+import { ProjectHandle } from "./scope/project-handle.cjs";
+import { Projects } from "./scope/projects.cjs";
+import type { EnvironmentHandle } from "./scope/environment-handle.cjs";
+import type { SearchPage } from "./search/search-page.cjs";
+import type { SearchQuery } from "./search/search-query.cjs";
+import type { SiloOptions } from "./silo-options.cjs";
+/**
+ * One silo instance. Navigate it the way the API is shaped:
+ * `silo.project("acme").environment("prod").collection<Post>("posts")`.
+ *
+ * Handles are value objects and make no request, so nothing in a chain needs
+ * an `await` until the call at the end. There is deliberately no default
+ * project or environment: both names are always given.
+ */
+export declare class Silo {
+    /** The projects this key can see, and creating one. */
+    readonly projects: Projects;
+    /** The media catalog. Media is instance-global, so it takes no scope. */
+    readonly media: Media;
+    private readonly options;
+    private readonly transport;
+    constructor(options: SiloOptions);
+    /** One project, by the name every path addresses it with. */
+    project(name: string): ProjectHandle;
+    /** `silo.project(p).environment(e)` in one call. Still takes both names. */
+    scope(project: string, environment: string): EnvironmentHandle;
+    /**
+     * Search everything this key can read. The narrower reaches are
+     * `environment.search()` and `collection.search()`, so a reach is always
+     * the receiver and never an argument that could be forgotten.
+     */
+    search(query: SearchQuery, options?: RequestOptions): Promise<SearchPage>;
+    /** Liveness and version. The one route that is never authenticated. */
+    health(options?: RequestOptions): Promise<HealthReport>;
+    /** The same instance read with a different key. */
+    withKey(key: string | undefined): Silo;
+    /** The same options pointed at a different server. */
+    withUrl(url: string): Silo;
+}