@noy-db/in-pinia 0.2.0-pre.9 → 0.3.0-pre.2

package/dist/index.d.cts

@@ -1,608 +0,0 @@
-import * as pinia from 'pinia';
-import { StateTree, PiniaPlugin } from 'pinia';
-import { ShallowRef, Ref, ComputedRef } from 'vue';
-import { Query, Noydb, StandardSchemaV1, Vault, I18nTextDescriptor, DictKeyDescriptor, NoydbStore as NoydbStore$1, NoydbOptions, Role } from '@noy-db/hub';
-
-/**
- * i18n resolution mode for a store's reads.
- * - `'raw'` (default) — items keep `{ [locale]: string }` maps (today's behavior).
- * - `'follow'` — resolve to the global `useNoydbI18n` locale; re-read on flip.
- * - `{ locale, fallback? }` — pin to a fixed locale or own ref.
- */
-type NoydbStoreI18nMode = 'raw' | 'follow' | {
-    locale: string | Ref<string>;
-    fallback?: string | readonly string[];
-};
-/**
- * Reactive handle returned by `store.liveQuery(fn)`. Mirrors a hub
- * `LiveQuery<R>` into Vue refs; `items` updates on every left- or
- * joined-right-side mutation, `error` carries re-run errors as state
- * (a `DanglingReferenceError` in strict join mode is the common case),
- * `stop()` tears down upstream subscriptions. Auto-disposed on scope
- * teardown when called inside a Vue setup / Pinia store body.
- */
-interface NoydbLiveQuery<R> {
-    items: ShallowRef<readonly R[]>;
-    error: Ref<Error | null>;
-    stop(): void;
-}
-/**
- * Options accepted by `defineNoydbStore`.
- *
- * Generic `T` is the record shape — defaults to `unknown` if the caller
- * doesn't supply a type. Use `defineNoydbStore<Invoice>('invoices', {...})`
- * for full type safety.
- */
-interface NoydbStoreOptions<T> {
-    /** Vault (tenant) name. */
-    vault: string;
-    /** Collection name within the vault. Defaults to the store id. */
-    collection?: string;
-    /**
-     * Optional explicit Noydb instance. If omitted, the store resolves the
-     * globally bound instance via `getActiveNoydb()`.
-     */
-    noydb?: Noydb | null;
-    /**
-     * If true (default), hydration kicks off immediately when the store is
-     * first instantiated. If false, hydration is deferred until the first
-     * call to `refresh()` or any read accessor.
-     */
-    prefetch?: boolean;
-    /**
-     * Optional schema validator.
-     *
-     * Accepts any [Standard Schema v1](https://standardschema.dev) validator
-     * — Zod, Valibot, ArkType, Effect Schema, etc. The same validator is
-     * installed on the underlying `Collection`, so every `put()` is
-     * validated **before encryption** and every read is validated **after
-     * decryption**. The store's `add`/`update` methods inherit this
-     * validation automatically; no duplicate `.parse()` call is needed.
-     *
-     * Schema-less stores behave exactly as before (no validation, no
-     * perf cost, backwards compatible with usage).
-     */
-    schema?: StandardSchemaV1<unknown, T>;
-    /**
-     * Optional per-field attestation schema. When set, it's installed on the
-     * underlying `Collection` (alongside `schema`) so `vault.issueAttestation(name, id)`
-     * can commit the declared fields against the firm's signing key — see
-     * `@noy-db/attestation` `AttestationFieldSchema`. Stores without it behave as before.
-     */
-    attestation?: NonNullable<Parameters<Vault['collection']>[1]>['attestation'];
-    /**
-     * If true, the collection persists a JSON Schema baseline of `schema` so the
-     * schema-update protocol can detect drift on later opens. Forwarded as-is to
-     * the underlying `Collection`. Required for `schemaUpdate` to take effect.
-     */
-    persistJsonSchema?: NonNullable<Parameters<Vault['collection']>[1]>['persistJsonSchema'];
-    /**
-     * Ordered schema-update strategies (e.g. `coordinatedCutover`, `additiveOnly`,
-     * `lockSchema`) applied when a stored baseline differs from the current
-     * `schema`. Forwarded as-is to the underlying `Collection`. Requires
-     * `persistJsonSchema: true` (drift detection needs the persisted baseline).
-     * Lets a `defineNoydbStore`-defined collection opt into migration tracking
-     * declaratively, without a pre-registration `vault.collection(...)` call.
-     */
-    schemaUpdate?: NonNullable<Parameters<Vault['collection']>[1]>['schemaUpdate'];
-    /**
-     * Per-field `i18nText()` descriptors. Forwarded to the underlying
-     * `Collection` so locale resolution and required-translation validation
-     * run declaratively without a separate `vault.collection(name, { i18nFields })`
-     * pre-registration call.
-     */
-    i18nFields?: Record<string, I18nTextDescriptor>;
-    /**
-     * Per-field `dictKey()` descriptors. Forwarded to the underlying
-     * `Collection` so dictionary label resolution runs declaratively.
-     */
-    dictKeyFields?: Record<string, DictKeyDescriptor>;
-    /**
-     * How the store resolves i18nText/dictKey fields on read.
-     * Default `'raw'` — items keep `{ [locale]: string }` maps (today's
-     * behavior; zero breaking change). `'follow'` resolves to the global
-     * `useNoydbI18n` locale and re-reads when it changes. `{ locale }`
-     * pins to a fixed locale or own ref. Set `'raw'` for stores whose maps
-     * feed identity/export reads or a per-cell bilingual toggle.
-     */
-    i18n?: NoydbStoreI18nMode;
-}
-/**
- * The runtime shape of the store returned by `defineNoydbStore`.
- * Exposed as a public type so consumers can write `useStore: ReturnType<typeof useInvoices>`.
- */
-interface NoydbStore<T> {
-    items: Ref<T[]>;
-    count: ComputedRef<number>;
-    $ready: Promise<void>;
-    byId(id: string): T | undefined;
-    add(id: string, record: T): Promise<void>;
-    update(id: string, record: T): Promise<void>;
-    remove(id: string): Promise<void>;
-    refresh(): Promise<void>;
-    query(): Query<T>;
-    liveQuery<R = T>(build: (q: Query<T>) => Query<R>): NoydbLiveQuery<R>;
-}
-/**
- * Define a Pinia store that's wired to a NOYDB collection.
- *
- * Generic T defaults to `unknown` — pass `<MyType>` for full type inference.
- *
- * @example
- * ```ts
- * import { defineNoydbStore } from '@noy-db/in-pinia';
- *
- * export const useInvoices = defineNoydbStore<Invoice>('invoices', {
- *   vault: 'C101',
- *   schema: InvoiceSchema, // optional
- * });
- * ```
- */
-declare function defineNoydbStore<T>(id: string, options: NoydbStoreOptions<T>): pinia.StoreDefinition<string, Pick<{
-    items: Ref<T[], T[]>;
-    count: ComputedRef<number>;
-    $ready: Promise<void>;
-    byId: (id: string) => T | undefined;
-    add: (id: string, record: T) => Promise<void>;
-    update: (id: string, record: T) => Promise<void>;
-    remove: (id: string) => Promise<void>;
-    refresh: () => Promise<void>;
-    query: () => Query<T>;
-    liveQuery: <R = T>(build: (q: Query<T>) => Query<R>) => NoydbLiveQuery<R>;
-}, "items" | "$ready">, Pick<{
-    items: Ref<T[], T[]>;
-    count: ComputedRef<number>;
-    $ready: Promise<void>;
-    byId: (id: string) => T | undefined;
-    add: (id: string, record: T) => Promise<void>;
-    update: (id: string, record: T) => Promise<void>;
-    remove: (id: string) => Promise<void>;
-    refresh: () => Promise<void>;
-    query: () => Query<T>;
-    liveQuery: <R = T>(build: (q: Query<T>) => Query<R>) => NoydbLiveQuery<R>;
-}, "count">, Pick<{
-    items: Ref<T[], T[]>;
-    count: ComputedRef<number>;
-    $ready: Promise<void>;
-    byId: (id: string) => T | undefined;
-    add: (id: string, record: T) => Promise<void>;
-    update: (id: string, record: T) => Promise<void>;
-    remove: (id: string) => Promise<void>;
-    refresh: () => Promise<void>;
-    query: () => Query<T>;
-    liveQuery: <R = T>(build: (q: Query<T>) => Query<R>) => NoydbLiveQuery<R>;
-}, "byId" | "add" | "update" | "remove" | "refresh" | "query" | "liveQuery">>;
-
-/**
- * Active NOYDB instance binding.
- *
- * `defineNoydbStore` resolves the `Noydb` instance from one of three places,
- * in priority order:
- *
- *   1. The store options' explicit `noydb:` field (highest precedence — useful
- *      for tests and multi-database apps).
- *   2. A globally bound instance set via `setActiveNoydb()` — this is what the
- *      Nuxt module's runtime plugin and playground apps use.
- *   3. Throws a clear error if neither is set.
- *
- * Keeping the binding pluggable means tests can pass an instance directly
- * without polluting global state.
- */
-
-/** Bind a Noydb instance globally. Called by the Nuxt module / app plugin. */
-declare function setActiveNoydb(instance: Noydb | null): void;
-/** Returns the globally bound Noydb instance, or null if none. */
-declare function getActiveNoydb(): Noydb | null;
-/**
- * Resolve the Noydb instance to use for a store. Throws if no instance is
- * bound — the error message points the developer at the three options.
- */
-declare function resolveNoydb(explicit?: Noydb | null): Noydb;
-
-/** Minimal vault shape needed to sync an ambient locale. */
-interface LocaleSyncable {
-    setLocale(locale: string | undefined): void;
-}
-interface SetLocaleOptions {
-    /**
-     * Vault(s) to ALSO update via `vault.setLocale` (opt-in). Omit to keep
-     * the operation state-only — the safe default for locale-less vaults.
-     */
-    readonly syncVault?: LocaleSyncable | readonly LocaleSyncable[];
-}
-declare const useNoydbI18n: pinia.StoreDefinition<"noydb-i18n", Pick<{
-    locale: Ref<string, string>;
-    fallback: Ref<string[], string[]>;
-    setLocale: (l: string, opts?: SetLocaleOptions) => void;
-    setFallback: (chain: string[]) => void;
-    bindTo: (source: Ref<string>, opts?: {
-        immediate?: boolean;
-    }) => () => void;
-}, "locale" | "fallback">, Pick<{
-    locale: Ref<string, string>;
-    fallback: Ref<string[], string[]>;
-    setLocale: (l: string, opts?: SetLocaleOptions) => void;
-    setFallback: (chain: string[]) => void;
-    bindTo: (source: Ref<string>, opts?: {
-        immediate?: boolean;
-    }) => () => void;
-}, never>, Pick<{
-    locale: Ref<string, string>;
-    fallback: Ref<string[], string[]>;
-    setLocale: (l: string, opts?: SetLocaleOptions) => void;
-    setFallback: (chain: string[]) => void;
-    bindTo: (source: Ref<string>, opts?: {
-        immediate?: boolean;
-    }) => () => void;
-}, "setLocale" | "setFallback" | "bindTo">>;
-
-/**
- * `useI18nField` — a reactive `pickLang` for a single i18nText map.
- *
- * Resolves a `{ [locale]: string }` map to the active locale, recomputing
- * when the locale (or a reactive source) changes. Uses hub's
- * `resolveI18nText` with `policy: 'null'`, so it never throws and never
- * yields `undefined` — `null` when no locale (and no fallback) resolves.
- *
- * Follows the global `useNoydbI18n` locale/fallback unless overridden.
- * Ideal for resolving one field at the edge while siblings stay raw
- * (e.g. a bilingual section reading raw maps).
- *
- * @public
- */
-
-type MapSource = Record<string, string> | (() => Record<string, string> | undefined | null);
-interface UseI18nFieldOptions {
-    /** Override the active locale (string or ref). Defaults to the global. */
-    readonly locale?: string | Ref<string>;
-    /** Override the fallback chain. Defaults to the global. */
-    readonly fallback?: string | readonly string[];
-}
-declare function useI18nField(source: MapSource, opts?: UseI18nFieldOptions): Ref<string | null>;
-
-/**
- * `useDictLabel(name, options)` — Vue composable for rendering
- * `dictKey` fields at template time.
- *
- * The i18n boundary pattern has records store a **stable key**; the
- * label lives in a reserved `_dict_<name>` collection and is resolved
- * at render time. Every Vue / Nuxt consumer ends up writing the same
- * wrapper — this composable replaces that boilerplate.
- *
- * ```vue
- * <script setup lang="ts">
- *   import { useDictLabel } from '@noy-db/in-pinia'
- *   const label = useDictLabel('invoiceStatus')
- * </script>
- *
- * <template>
- *   <td v-for="inv in invoices" :key="inv.id">
- *     {{ label(inv.status).value }}
- *   </td>
- * </template>
- * ```
- *
- * ## Reactivity
- *
- * `label(key)` returns a `Ref<string>` that updates when the locale
- * changes (via the passed-in `locale` ref).
- *
- * **Known limitation:** mutations via `vault.dictionary(name).put()`
- * bypass the Collection emitter — the hub's `DictionaryHandle` writes
- * through the adapter directly, so labels cached by this composable
- * won't refresh for those writes until either (a) the locale changes
- * or (b) the caller re-creates the composable. Tracked as a
- * hub follow-up (route dict writes through the Collection emitter).
- *
- * The underlying fetch is async, so a newly-constructed label starts
- * at its "missing" sentinel (the key itself by default) and updates
- * to the resolved string within one tick.
- *
- * @module
- */
-
-interface UseDictLabelOptions {
-    /**
-     * Explicit vault. Either a `Vault` instance or its name. When a
-     * name is provided the composable calls `db.vault(name)` — which
-     * requires the vault to already be open via
-     * `await db.openVault(name)` elsewhere.
-     *
-     * When omitted, uses the currently-active vault on the global
-     * Noydb instance set via `setActiveNoydb()`. If no vault is open
-     * and none is provided, setup throws.
-     */
-    readonly vault?: Vault | string;
-    /**
-     * Active locale. Pass a `Ref<string>` for live reactivity
-     * (e.g. `useI18n().locale` from vue-i18n, or `useLocale()` from a
-     * Nuxt module). A bare string is wrapped in a static ref.
-     * Defaults to `'en'`.
-     */
-    readonly locale?: Ref<string> | string;
-    /**
-     * Fallback locale chain — evaluated in order when the primary
-     * locale has no translation. Use `'any'` as the final entry to
-     * accept any available locale. Defaults to `['en', 'any']`.
-     */
-    readonly fallback?: string | readonly string[];
-    /**
-     * What to render when the key is absent from the dictionary.
-     *
-     *   - `'key'` (default) — return the key itself. Matches the hub's
-     *     stable-key invariant and surfaces typos during development.
-     *   - `'empty'` — return `''`. Best for cells where a missing
-     *     value should render blank.
-     *   - `'placeholder'` — return `⟨missing:{key}⟩` for visible
-     *     audit during QA.
-     */
-    readonly onMissing?: 'key' | 'empty' | 'placeholder';
-}
-/**
- * Build a reactive label lookup. Returns a factory `(key) => Ref<string>`.
- */
-declare function useDictLabel(dictionaryName: string, options?: UseDictLabelOptions): (key: string) => Ref<string>;
-
-/**
- * `createNoydbPiniaPlugin` — augmentation path for existing Pinia stores.
- *
- * Lets a developer take any existing `defineStore()` call and opt into NOYDB
- * persistence by adding a single `noydb:` option, without touching component
- * code. The plugin watches the chosen state key(s), encrypts on change, syncs
- * to a NOYDB collection, and rehydrates on store init.
- *
- * @example
- * ```ts
- * import { createPinia } from 'pinia';
- * import { createNoydbPiniaPlugin } from '@noy-db/in-pinia';
- * import { jsonFile } from '@noy-db/to-file';
- *
- * const pinia = createPinia();
- * pinia.use(createNoydbPiniaPlugin({
- *   adapter: jsonFile({ dir: './data' }),
- *   user: 'owner-01',
- *   secret: () => promptPassphrase(),
- * }));
- *
- * // existing store — add one option, no component changes:
- * export const useClients = defineStore('clients', {
- *   state: () => ({ list: [] as Client[] }),
- *   noydb: { vault: 'C101', collection: 'clients', persist: 'list' },
- * });
- * ```
- *
- * Design notes
- * ------------
- * - Each augmented store persists a SINGLE document at id `__state__`
- *   containing the picked keys. We don't try to map state arrays onto
- *   per-element records — that's `defineNoydbStore`'s territory.
- * - The Noydb instance is constructed lazily on first store-with-noydb
- *   instantiation, then memoized for the lifetime of the Pinia app.
- *   This means apps that don't actually use any noydb-augmented stores
- *   pay zero crypto cost.
- * - `secret` is a function so the passphrase can come from a prompt,
- *   biometric unlock, or session token — never stored in config.
- * - The plugin sets `store.$noydbReady` (a `Promise<void>`) and
- *   `store.$noydbError` (an `Error | null`) on every augmented store
- *   so components can await hydration and surface failures.
- */
-
-/**
- * Per-store NOYDB configuration. Attached to a Pinia store via the `noydb`
- * option inside `defineStore({ ..., noydb: {...} })`.
- *
- * `persist` selects which top-level state keys to mirror into NOYDB.
- * Pass a single key, an array of keys, or `'*'` to mirror the entire state.
- */
-interface StoreNoydbOptions<S extends StateTree = StateTree> {
-    /** Vault (tenant) name. */
-    vault: string;
-    /** Collection name within the vault. */
-    collection: string;
-    /**
-     * Which state keys to persist. Defaults to `'*'` (the entire state object).
-     * Pass a string or string[] to scope to specific keys.
-     */
-    persist?: keyof S | (keyof S)[] | '*';
-    /**
-     * Optional schema validator applied at the document level (the persisted
-     * subset of state, not individual records). Throws if validation fails on
-     * hydration — the store stays at its initial state and `$noydbError` is set.
-     */
-    schema?: {
-        parse: (input: unknown) => unknown;
-    };
-}
-/**
- * Configuration for `createNoydbPiniaPlugin`. Mirrors `NoydbOptions` but
- * makes `secret` a function so the passphrase can come from a prompt
- * rather than being stored in config.
- */
-interface NoydbPiniaPluginOptions {
-    /** The NOYDB store to use for persistence. */
-    adapter: NoydbStore$1;
-    /** User identifier (matches the keyring file). */
-    user: string;
-    /**
-     * Passphrase provider. Called once on first noydb-augmented store
-     * instantiation. Return a string or a Promise that resolves to one.
-     */
-    secret: () => string | Promise<string>;
-    /** Optional Noydb open-options forwarded to `createNoydb`. */
-    noydbOptions?: Partial<Omit<NoydbOptions, 'store' | 'user' | 'secret'>>;
-}
-/**
- * Create a Pinia plugin that wires NOYDB persistence into any store
- * declaring a `noydb:` option.
- *
- * Returns a `PiniaPlugin` directly usable with `pinia.use(...)`.
- */
-declare function createNoydbPiniaPlugin(opts: NoydbPiniaPluginOptions): PiniaPlugin;
-declare module 'pinia' {
-    interface DefineStoreOptionsBase<S extends StateTree, Store> {
-        /**
-         * Opt this store into NOYDB persistence via the
-         * `createNoydbPiniaPlugin` augmentation plugin.
-         *
-         * The chosen state keys are encrypted and persisted to the configured
-         * vault + collection on every mutation, and rehydrated on first
-         * store access.
-         */
-        noydb?: StoreNoydbOptions<S>;
-    }
-    interface PiniaCustomProperties {
-        /**
-         * Resolves once this store has finished its initial hydration from
-         * NOYDB. `undefined` for stores that don't declare a `noydb:` option.
-         */
-        $noydbReady?: Promise<void>;
-        /**
-         * Set when hydration or persistence fails. `null` while healthy.
-         * Plugins (and devtools) can poll this to surface storage errors.
-         */
-        $noydbError?: Error | null;
-        /**
-         * `true` if this store opted into NOYDB persistence via the `noydb:`
-         * option, `false` otherwise. Useful for debugging and devtools.
-         */
-        $noydbAugmented?: boolean;
-        /**
-         * Wait for all in-flight encrypted persistence puts to complete.
-         * Useful in tests for deterministic flushing, and in app code before
-         * unmounting components that just mutated the store.
-         */
-        $noydbFlush?: () => Promise<void>;
-    }
-}
-
-/**
- * `useCapabilityGrant` — Vue/Pinia composable for time-boxed
- * capability approval flows.
- *
- * The composable orchestrates a request → approve → expire / release
- * lifecycle for a session-scoped capability. It manages UI state,
- * persists the request to a reserved `_capability_requests` collection
- * so a separate approver session can see it, and tracks TTL with
- * auto-revert.
- *
- * **It does NOT itself flip capability bits.** Capability mechanisms
- * vary across adopters: tier-based deployments wire `onGrant` to
- * `vault.elevate(tier, opts)`; keyring-based deployments wire it to
- * `db.grant(...)`; custom deployments do their own thing. Keeping the
- * actual flip behind a callback avoids introducing a parallel
- * "capability elevation" primitive in hub when the existing
- * `vault.elevate()` already covers the time-boxed-grant pattern.
- *
- * ## State machine
- *
- *   idle  ─── .request() ───────►  requested
- *   requested  ─── .approve() ──►  granted
- *   granted    ─── TTL expires ─►  idle
- *   granted    ─── .release() ──►  idle
- *
- * @module
- */
-
-/** Reserved internal collection that holds capability-grant lifecycle records. */
-declare const CAPABILITY_REQUESTS_COLLECTION = "_capability_requests";
-type CapabilityGrantState = 'idle' | 'requested' | 'granted' | 'expired';
-/**
- * On-disk shape of a capability-grant lifecycle record. Persisted in
- * the reserved {@link CAPABILITY_REQUESTS_COLLECTION}. Encrypted with
- * that collection's DEK at the storage layer; the in-memory shape
- * here is plaintext.
- *
- * The audit trail invariant: this record carries metadata only —
- * capability name, roles, ttl, reason. Never plaintext payload.
- */
-interface CapabilityGrantRecord {
-    readonly id: string;
-    readonly capability: string;
-    readonly requestedBy: string;
-    readonly approverRole: Role;
-    readonly reason: string;
-    readonly ttlMs: number;
-    readonly status: 'requested' | 'granted' | 'released' | 'expired';
-    readonly requestedAt: string;
-    readonly approvedBy?: string;
-    readonly approvedAt?: string;
-    readonly expiresAt?: string;
-}
-interface UseCapabilityGrantOptions {
-    /** TTL in milliseconds for the granted window. */
-    readonly ttlMs: number;
-    /** Role required to call `.approve()`. Mismatch throws on `.approve()`. */
-    readonly approver: Role;
-    /** Audit-ledger string. Stamped on the request record; no plaintext payload. */
-    readonly reason: string;
-    /**
-     * Optional explicit vault. Either a `Vault` instance or its name.
-     * When omitted, resolves the active Noydb instance via
-     * `setActiveNoydb()` and opens the first vault the caller has
-     * already loaded.
-     */
-    readonly vault: Vault | string;
-    /**
-     * Called on the approver's session when `.approve()` succeeds. Wire
-     * this to whatever capability flip your codebase uses —
-     * `vault.elevate(tier, opts)` for tier-based deployments,
-     * `db.grant(...)` for keyring-based, custom for custom.
-     *
-     * The composable does NOT enforce that the capability was actually
-     * granted — it just tracks the lifecycle. The post-expiry "gated
-     * call throws" contract comes from the underlying mechanism the
-     * callback wires up (e.g., `ElevationExpiredError` from
-     * `vault.elevate`'s lazy TTL check).
-     */
-    readonly onGrant?: (ctx: {
-        record: CapabilityGrantRecord;
-        vault: Vault;
-    }) => void | Promise<void>;
-    /**
-     * Called when the grant ends (TTL expiry OR voluntary release).
-     * Mirror of `onGrant`. Idempotent — may be called twice if release
-     * and expiry race; callers should no-op on the second invocation.
-     */
-    readonly onRelease?: (ctx: {
-        record: CapabilityGrantRecord;
-        vault: Vault;
-        cause: 'released' | 'expired';
-    }) => void | Promise<void>;
-}
-interface UseCapabilityGrantReturn {
-    readonly state: Ref<CapabilityGrantState>;
-    /** Milliseconds remaining on the granted window; 0 outside `granted`. */
-    readonly timeRemaining: ComputedRef<number>;
-    /** Most recent error from request/approve/release (resets on next op). */
-    readonly error: Ref<Error | null>;
-    /** Issue a request. State must be `idle`. */
-    request(): Promise<void>;
-    /** Approve a pending request. State must be `requested`. */
-    approve(): Promise<void>;
-    /** Voluntarily revoke an active grant. State must be `granted`. */
-    release(): Promise<void>;
-}
-/**
- * Build a reactive capability-grant lifecycle handle.
- *
- * @example Tier-based capability flip
- * ```ts
- * let elevated: ElevatedHandle | null = null
- * const grant = useCapabilityGrant('canExportPlaintext', {
- *   vault: 'V1',
- *   ttlMs: 15 * 60_000,
- *   approver: 'admin',
- *   reason: 'bulk export',
- *   onGrant: async ({ vault, record }) => {
- *     elevated = await vault.elevate(2, {
- *       ttlMs: record.ttlMs,
- *       reason: record.reason,
- *     })
- *   },
- *   onRelease: async () => { await elevated?.release(); elevated = null },
- * })
- * ```
- */
-declare function useCapabilityGrant(capability: string, options: UseCapabilityGrantOptions): UseCapabilityGrantReturn;
-
-export { CAPABILITY_REQUESTS_COLLECTION, type CapabilityGrantRecord, type CapabilityGrantState, type LocaleSyncable, type NoydbLiveQuery, type NoydbPiniaPluginOptions, type NoydbStore, type NoydbStoreOptions, type SetLocaleOptions, type StoreNoydbOptions, type UseCapabilityGrantOptions, type UseCapabilityGrantReturn, type UseDictLabelOptions, type UseI18nFieldOptions, createNoydbPiniaPlugin, defineNoydbStore, getActiveNoydb, resolveNoydb, setActiveNoydb, useCapabilityGrant, useDictLabel, useI18nField, useNoydbI18n };