@siafoundation/sia-storage 0.0.13 → 0.1.0

package/wasm/sia_storage_wasm.d.ts

@@ -17,25 +17,13 @@ export interface DownloadOptions {
 
 
 
-export interface SealedObject {
-    encryptedDataKey: string;
-    slabs: Slab[];
-    dataSignature: string;
-    encryptedMetadataKey?: string;
-    encryptedMetadata?: string;
-    metadataSignature: string;
-    createdAt: string;
-    updatedAt: string;
-}
-
-
-
 export interface Sector {
     root: string;
     hostKey: string;
 }
 
 export interface Slab {
+    version: number;
     encryptionKey: string;
     minShards: number;
     offset: number;
@@ -44,6 +32,7 @@ export interface Slab {
 }
 
 export interface PinnedSlab {
+    version: number;
     id: string;
     encryptionKey: string;
     minShards: number;
@@ -62,6 +51,14 @@ export interface Host {
 
 
 export interface UploadOptions {
+    dataShards?: number;
+    parityShards?: number;
+    maxBufferedSlabs?: number;
+    startOffset?: bigint;
+    onShardUploaded?: (progress: ShardProgress) => void;
+}
+
+export interface PackedUploadOptions {
     dataShards?: number;
     parityShards?: number;
     maxBufferedSlabs?: number;
@@ -73,7 +70,13 @@ export interface UploadOptions {
 interface Sdk {
     download(object: PinnedObject, options?: DownloadOptions): ReadableStream;
     upload(object: PinnedObject, source: ReadableStream, options?: UploadOptions): Promise<PinnedObject>;
-    uploadPacked(options?: UploadOptions): PackedUpload;
+    uploadPacked(options?: PackedUploadOptions): PackedUpload;
+}
+
+
+
+interface SharedSdk {
+    download(object: PinnedObject, options?: DownloadOptions): ReadableStream;
 }
 
 
@@ -89,7 +92,7 @@ export interface App {
 }
 
 /**
- * Information about the user\'s account on the indexer.
+ * Information about the user's account on the indexer.
  */
 export interface Account {
     accountKey: string;
@@ -126,7 +129,7 @@ export interface HostQuery {
 }
 
 /**
- * TS interface for `Builder::new`\'s `app` parameter. Field names must
+ * TS interface for `Builder::new`'s `app` parameter. Field names must
  * match the Reflect reads in `helpers::make_app_metadata`.
  */
 export interface AppMetadata {
@@ -139,7 +142,7 @@ export interface AppMetadata {
 }
 
 /**
- * TS interface for `Sdk::objectEvents`\'s `cursor` parameter. Field
+ * TS interface for `Sdk::objectEvents`'s `cursor` parameter. Field
  * names must match the Reflect reads in `sdk.rs`.
  */
 export interface ObjectsCursor {
@@ -147,7 +150,30 @@ export interface ObjectsCursor {
     after: Date;
 }
 
-export type SealedObject = SealedObject;
+/**
+ * What a recipient can see about the sharing key they hold. The counts are a
+ * snapshot, not a live view.
+ */
+export interface KeyStats {
+    objectCount: number;
+    objectSize: number;
+    pinnedData: number;
+    pinnedSize: number;
+    expiresAt: Date | undefined;
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+export type SealedObject = {
+    encryptedDataKey: string;
+    slabs: Slab[];
+    dataSignature: string;
+    encryptedMetadataKey?: string;
+    encryptedMetadata?: string;
+    metadataSignature: string;
+    createdAt: string;
+    updatedAt: string;
+};
 
 
 /**
@@ -190,14 +216,38 @@ export class AppKey {
 export class Builder {
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Connects using a pre-authorized key, bypassing the interactive approval
+     * flow, and returns a Sdk. `preAuthorizedKeySeed` is the 32-byte
+     * pre-authorized private key (Uint8Array); `mnemonic` derives the app key.
+     */
+    connectPreAuthorized(pre_authorized_key_seed: Uint8Array, mnemonic: string): Promise<Sdk>;
     /**
      * Attempts to connect using an existing AppKey.
      * Returns a Sdk if the key is valid, or undefined if not registered.
      */
     connected(app_key: AppKey): Promise<Sdk | undefined>;
+    /**
+     * Returns whether `mnemonic` derives an application key that is already
+     * registered with the indexer. Unlike `register`, the builder remains
+     * usable. Only valid after `waitForApproval` has resolved.
+     */
+    matchesExistingAppKey(mnemonic: string): Promise<boolean>;
     constructor(indexer_url: string, app: AppMetadata);
+    /**
+     * Returns whether the connect key the user approved with already has an
+     * account for this application. Only valid after `waitForApproval` has
+     * resolved.
+     *
+     * The connect key may have accounts under more than one recovery phrase.
+     * Use `matchesExistingAppKey` to check a particular phrase.
+     */
+    reconnecting(): boolean;
     /**
      * Completes registration and returns a Sdk instance.
+     *
+     * A different recovery phrase registers a new application key even when
+     * `reconnecting()` is true.
      */
     register(mnemonic: string): Promise<Sdk>;
     /**
@@ -242,6 +292,27 @@ export class IntoUnderlyingSource {
     pull(controller: ReadableStreamDefaultController): Promise<any>;
 }
 
+/**
+ * The indexer's record for a sharing key, including how many objects it grants
+ * access to and how much space they use. The counts are a snapshot, not a live
+ * view.
+ */
+export class KeyRecord {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    readonly description: string;
+    /**
+     * The key this record describes.
+     */
+    readonly key: SharingKey;
+    /**
+     * A snapshot of how many objects the key grants access to and how much
+     * space they use.
+     */
+    readonly stats: KeyStats;
+}
+
 /**
  * An object event from the indexer.
  */
@@ -285,7 +356,9 @@ export class PackedUpload {
      *
      * If the reader errors part-way, it's safe to continue calling
      * [add](Self::add); no object is registered for the failed call. Or call
-     * [finalize](Self::finalize) to collect the objects added so far.
+     * [finalize](Self::finalize) to collect the objects added so far. Bytes
+     * read before the error remain in the current slab as padding and stay
+     * counted in [length](Self::length) and [remaining](Self::remaining).
      *
      * ```js
      * const packed = sdk.uploadPacked();
@@ -369,6 +442,10 @@ export class PinnedObject {
      * Returns the slabs that make up the object.
      */
     slabs(): Slab[];
+    /**
+     * Returns a new object truncated to the requested length.
+     */
+    truncate(length: bigint): PinnedObject;
     /**
      * Updates the object's metadata.
      */
@@ -395,6 +472,10 @@ export class Sdk {
      * Returns the AppKey used by this SDK instance.
      */
     appKey(): AppKey;
+    /**
+     * Creates a sharing key. Attach objects to it with `Sdk.shareObject`.
+     */
+    createSharingKey(description: string, expires_at?: Date | null): Promise<SharingKey>;
     /**
      * Deletes an object from the indexer by its hex ID.
      */
@@ -427,6 +508,17 @@ export class Sdk {
      * Returns object events for syncing local state with the indexer.
      */
     objectEvents(cursor: ObjectsCursor | null | undefined, limit: number): Promise<ObjectEvent[]>;
+    /**
+     * Resolves a share URL (sia://...) and returns the shared object.
+     * The encryption key is extracted from the URL fragment (never sent
+     * to the indexer).
+     */
+    objectFromShareUrl(share_url: string): Promise<PinnedObject>;
+    /**
+     * Generates a signed share URL for an object. Anyone with the URL can
+     * download and decrypt the object until `validUntil`.
+     */
+    objectShareUrl(object: PinnedObject, valid_until: Date): string;
     /**
      * Pins an object to the indexer so it persists beyond temporary storage.
      */
@@ -436,20 +528,38 @@ export class Sdk {
      */
     pruneSlabs(): Promise<void>;
     /**
-     * Generates a signed share URL for an object. Anyone with the URL can
-     * download and decrypt the object until `validUntil`.
+     * Deletes a sharing key along with all of its attachments, revoking
+     * recipients' access. Account tokens already issued stay valid until they
+     * expire, so a download in flight can keep reading for up to five minutes.
      */
-    shareObject(object: PinnedObject, valid_until: Date): string;
+    revokeSharingKey(key: SharingKey): Promise<void>;
     /**
-     * Resolves a share URL (sia://...) and returns the shared object.
-     * The encryption key is extracted from the URL fragment (never sent
-     * to the indexer).
+     * Attaches an object to a sharing key, re-sealing its encryption keys under
+     * the key so recipients can decrypt it. Attaching an already-attached
+     * object replaces its re-sealed keys, so a failed call can be retried.
+     */
+    shareObject(key: SharingKey, object: PinnedObject): Promise<void>;
+    /**
+     * Lists and decrypts a page of the objects a sharing key grants access to.
+     */
+    sharedObjects(key: SharingKey, offset: number, limit: number): Promise<PinnedObject[]>;
+    /**
+     * Fetches the indexer's record for a key, including its counts.
+     */
+    sharingKey(key: SharingKey): Promise<KeyRecord>;
+    /**
+     * Lists the account's sharing keys, most recently created first.
      */
-    sharedObject(share_url: string): Promise<PinnedObject>;
+    sharingKeys(offset: number, limit: number): Promise<KeyRecord[]>;
     /**
      * Retrieves a pinned slab from the indexer by its hex ID.
      */
     slab(slab_id: string): Promise<PinnedSlab>;
+    /**
+     * Detaches an object from a sharing key, leaving the key and its other
+     * attachments in place.
+     */
+    unshareObject(key: SharingKey, object: PinnedObject): Promise<void>;
     /**
      * Updates an object's metadata on the indexer.
      */
@@ -476,6 +586,73 @@ export class Sdk {
     uploadPacked(options?: any | null): PackedUpload;
 }
 
+/**
+ * A read-only SDK for the objects a sharing key grants access to.
+ *
+ * Unlike `Sdk`, it authenticates with a sharing key rather than an app key and
+ * cannot upload, pin, or delete. Downloads are paid for by the key's owner.
+ */
+export class SharedSdk {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Connects to `indexerUrl` as the recipient of the sharing key derived
+     * from `seed`, which is the hex string the key's owner handed out.
+     */
+    static connect(indexer_url: string, seed: string): Promise<SharedSdk>;
+    /**
+     * Streams a shared object's data.
+     */
+    download(object: PinnedObject, options?: any | null): ReadableStream;
+    /**
+     * Returns the hosts serving this key's objects, optionally filtered by a
+     * HostQuery. Mirrors `Sdk.hosts()` but is scoped to the sharing key, so the
+     * set is already limited to hosts holding its objects.
+     */
+    hosts(query?: HostQuery | null): Promise<Host[]>;
+    /**
+     * Fetches and decrypts one object the key grants access to.
+     */
+    object(id: string): Promise<PinnedObject>;
+    /**
+     * Lists and decrypts a page of the objects the key grants access to.
+     */
+    objects(offset: number, limit: number): Promise<PinnedObject[]>;
+    /**
+     * Fetches the sharing key's stats from the indexer.
+     */
+    stats(): Promise<KeyStats>;
+}
+
+/**
+ * A sharing key, granting read-only access to the objects attached to it.
+ *
+ * It is just the credential; the operations that use it live on `Sdk`.
+ */
+export class SharingKey {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Imports a sharing key from the hex seed its owner handed out.
+     *
+     * Pass the string returned by [seed](Self::seed).
+     */
+    static fromSeed(seed: string): SharingKey;
+    /**
+     * Returns the seed a recipient needs to read the key's objects, as hex.
+     *
+     * It is the whole credential. Pair it with the indexer's url in
+     * `SharedSdk.connect`.
+     */
+    seed(): string;
+    /**
+     * The key's public half, which identifies it.
+     */
+    readonly publicKey: string;
+}
+
 /**
  * Calculates the encoded size of data after erasure coding.
  */
@@ -512,17 +689,22 @@ export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_appkey_free: (a: number, b: number) => void;
     readonly __wbg_builder_free: (a: number, b: number) => void;
+    readonly __wbg_keyrecord_free: (a: number, b: number) => void;
     readonly __wbg_objectevent_free: (a: number, b: number) => void;
     readonly __wbg_packedupload_free: (a: number, b: number) => void;
     readonly __wbg_pinnedobject_free: (a: number, b: number) => void;
     readonly __wbg_sdk_free: (a: number, b: number) => void;
+    readonly __wbg_sharedsdk_free: (a: number, b: number) => void;
     readonly appkey_export: (a: number) => [number, number];
     readonly appkey_new: (a: number, b: number) => [number, number, number];
     readonly appkey_publicKey: (a: number) => [number, number];
     readonly appkey_sign: (a: number, b: number, c: number) => [number, number];
     readonly appkey_verifySignature: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+    readonly builder_connectPreAuthorized: (a: number, b: number, c: number, d: number, e: number) => any;
     readonly builder_connected: (a: number, b: number) => any;
+    readonly builder_matchesExistingAppKey: (a: number, b: number, c: number) => any;
     readonly builder_new: (a: number, b: number, c: any) => [number, number, number];
+    readonly builder_reconnecting: (a: number) => [number, number, number];
     readonly builder_register: (a: number, b: number, c: number) => any;
     readonly builder_requestConnection: (a: number) => any;
     readonly builder_responseUrl: (a: number) => [number, number, number, number];
@@ -530,6 +712,9 @@ export interface InitOutput {
     readonly encodedSize: (a: number, b: number, c: number) => number;
     readonly generateRecoveryPhrase: () => [number, number];
     readonly init: () => void;
+    readonly keyrecord_description: (a: number) => [number, number];
+    readonly keyrecord_key: (a: number) => number;
+    readonly keyrecord_stats: (a: number) => [number, number, number];
     readonly objectevent_deleted: (a: number) => number;
     readonly objectevent_id: (a: number) => [number, number];
     readonly objectevent_object: (a: number) => number;
@@ -547,28 +732,46 @@ export interface InitOutput {
     readonly pinnedobject_metadata: (a: number) => [number, number];
     readonly pinnedobject_new: () => number;
     readonly pinnedobject_open: (a: number, b: any) => [number, number, number];
-    readonly pinnedobject_seal: (a: number, b: number) => any;
+    readonly pinnedobject_seal: (a: number, b: number) => [number, number, number];
     readonly pinnedobject_size: (a: number) => number;
     readonly pinnedobject_slabs: (a: number) => [number, number, number];
+    readonly pinnedobject_truncate: (a: number, b: bigint) => number;
     readonly pinnedobject_updateMetadata: (a: number, b: number, c: number) => void;
     readonly pinnedobject_updatedAt: (a: number) => any;
     readonly sdk_account: (a: number) => any;
     readonly sdk_appKey: (a: number) => number;
+    readonly sdk_createSharingKey: (a: number, b: number, c: number, d: number) => any;
     readonly sdk_deleteObject: (a: number, b: number, c: number) => any;
     readonly sdk_download: (a: number, b: number, c: number) => [number, number, number];
     readonly sdk_hosts: (a: number, b: number) => any;
     readonly sdk_object: (a: number, b: number, c: number) => any;
     readonly sdk_objectEvents: (a: number, b: any, c: number) => any;
+    readonly sdk_objectFromShareUrl: (a: number, b: number, c: number) => any;
+    readonly sdk_objectShareUrl: (a: number, b: number, c: any) => [number, number, number, number];
     readonly sdk_pinObject: (a: number, b: number) => any;
     readonly sdk_pruneSlabs: (a: number) => any;
-    readonly sdk_shareObject: (a: number, b: number, c: any) => [number, number, number, number];
-    readonly sdk_sharedObject: (a: number, b: number, c: number) => any;
+    readonly sdk_revokeSharingKey: (a: number, b: number) => any;
+    readonly sdk_shareObject: (a: number, b: number, c: number) => any;
+    readonly sdk_sharedObjects: (a: number, b: number, c: number, d: number) => any;
+    readonly sdk_sharingKey: (a: number, b: number) => any;
+    readonly sdk_sharingKeys: (a: number, b: number, c: number) => any;
     readonly sdk_slab: (a: number, b: number, c: number) => any;
+    readonly sdk_unshareObject: (a: number, b: number, c: number) => any;
     readonly sdk_updateObjectMetadata: (a: number, b: number) => any;
     readonly sdk_upload: (a: number, b: number, c: any, d: number) => any;
     readonly sdk_uploadPacked: (a: number, b: number) => [number, number, number];
     readonly setLogger: (a: any, b: any) => void;
+    readonly sharedsdk_connect: (a: number, b: number, c: number, d: number) => any;
+    readonly sharedsdk_download: (a: number, b: number, c: number) => [number, number, number];
+    readonly sharedsdk_hosts: (a: number, b: number) => any;
+    readonly sharedsdk_object: (a: number, b: number, c: number) => any;
+    readonly sharedsdk_objects: (a: number, b: number, c: number) => any;
+    readonly sharedsdk_stats: (a: number) => any;
+    readonly sharingkey_fromSeed: (a: number, b: number) => [number, number, number];
+    readonly sharingkey_publicKey: (a: number) => [number, number];
+    readonly sharingkey_seed: (a: number) => [number, number];
     readonly validateRecoveryPhrase: (a: number, b: number) => [number, number];
+    readonly __wbg_sharingkey_free: (a: number, b: number) => void;
     readonly __wbg_intounderlyingbytesource_free: (a: number, b: number) => void;
     readonly __wbg_intounderlyingsink_free: (a: number, b: number) => void;
     readonly __wbg_intounderlyingsource_free: (a: number, b: number) => void;
@@ -582,13 +785,13 @@ export interface InitOutput {
     readonly intounderlyingsink_write: (a: number, b: any) => any;
     readonly intounderlyingsource_cancel: (a: number) => void;
     readonly intounderlyingsource_pull: (a: number, b: any) => any;
-    readonly wasm_bindgen__convert__closures_____invoke__h466a94b78425b78b: (a: number, b: number, c: any) => [number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__hbf67b82a37e25b93: (a: number, b: number, c: any) => [number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__h466a94b78425b78b_3: (a: number, b: number, c: any) => [number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__h466a94b78425b78b_4: (a: number, b: number, c: any) => [number, number];
-    readonly wasm_bindgen__convert__closures_____invoke__h4815d933c518c891: (a: number, b: number, c: any, d: any) => void;
-    readonly wasm_bindgen__convert__closures_____invoke__h2aaa2940e06cecaf: (a: number, b: number, c: any) => void;
-    readonly wasm_bindgen__convert__closures_____invoke__hfcaa223eea581645: (a: number, b: number) => void;
+    readonly wasm_bindgen_baa1b51bcdcd1a91___convert__closures_____invoke___wasm_bindgen_baa1b51bcdcd1a91___JsValue__core_ed718c3d60ebd546___result__Result_____wasm_bindgen_baa1b51bcdcd1a91___JsError___true_: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen_baa1b51bcdcd1a91___convert__closures_____invoke___wasm_bindgen_baa1b51bcdcd1a91___sys__Undefined__core_ed718c3d60ebd546___result__Result_____wasm_bindgen_baa1b51bcdcd1a91___JsError___true_: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen_baa1b51bcdcd1a91___convert__closures_____invoke___wasm_bindgen_baa1b51bcdcd1a91___sys__Undefined__core_ed718c3d60ebd546___result__Result_____wasm_bindgen_baa1b51bcdcd1a91___JsError___true__3: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen_baa1b51bcdcd1a91___convert__closures_____invoke___wasm_bindgen_baa1b51bcdcd1a91___sys__Undefined__core_ed718c3d60ebd546___result__Result_____wasm_bindgen_baa1b51bcdcd1a91___JsError___true__4: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen_baa1b51bcdcd1a91___convert__closures_____invoke___js_sys_bdd470c3fe1f6d69___Function_fn_wasm_bindgen_baa1b51bcdcd1a91___JsValue_____wasm_bindgen_baa1b51bcdcd1a91___sys__Undefined___js_sys_bdd470c3fe1f6d69___Function_fn_wasm_bindgen_baa1b51bcdcd1a91___JsValue_____wasm_bindgen_baa1b51bcdcd1a91___sys__Undefined_______true_: (a: number, b: number, c: any, d: any) => void;
+    readonly wasm_bindgen_baa1b51bcdcd1a91___convert__closures_____invoke___wasm_bindgen_baa1b51bcdcd1a91___JsValue______true_: (a: number, b: number, c: any) => void;
+    readonly wasm_bindgen_baa1b51bcdcd1a91___convert__closures_____invoke_______true_: (a: number, b: number) => void;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_exn_store: (a: number) => void;