@siafoundation/sia-storage 0.0.14 → 0.1.1

package/dist/index.node.d.ts

@@ -1,5 +1,14 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
 /**
  * An AppKey is used to sign requests to the indexer.
  *
@@ -38,8 +47,49 @@ export declare class Builder {
   responseUrl(): string
   /** Waits for the connection request to be approved. */
   waitForApproval(): Promise<void>
-  /** Registers the application with the indexer using the provided mnemonic. */
+  /**
+   * 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
+  /**
+   * 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>
+  /**
+   * Registers the application with the indexer using the provided mnemonic.
+   *
+   * A different recovery phrase registers a new application key even when
+   * `reconnecting()` is true.
+   */
   register(mnemonic: string): Promise<Sdk>
+  /**
+   * Connects using a pre-authorized key, bypassing the interactive approval
+   * flow, and returns the SDK directly. `preAuthorizedKey` is the 32-byte
+   * pre-authorized private key seed; `mnemonic` derives the application key.
+   */
+  connectPreAuthorized(preAuthorizedKey: Buffer, mnemonic: string): Promise<Sdk>
+}
+
+/**
+ * The indexer's record for a sharing key, including how many objects it grants
+ * access to and how much space they use.
+ */
+export declare class KeyRecord {
+  /** The key this record describes. */
+  get key(): SharingKey
+  get description(): string
+  /**
+   * A snapshot of how many objects the key grants access to and how much
+   * space they use.
+   */
+  get stats(): KeyStats
 }
 
 /** An object event from the indexer. */
@@ -65,6 +115,8 @@ export declare class PackedUpload {
   length(): bigint
   /** Returns the number of slabs in the upload. */
   slabs(): bigint
+  /** Returns the optimal size of each slab in bytes. */
+  optimalDataSize(): bigint
   /**
    * Adds a new object to the upload. The data is read until EOF and packed into
    * the current slab. Returns the number of bytes consumed; call
@@ -120,6 +172,8 @@ export declare class PinnedObject {
   id(): string
   /** Returns the total size of the object. */
   size(): bigint
+  /** Returns a new object truncated to the requested length. */
+  truncate(length: bigint): PinnedObject
   /** Returns the total encoded size after erasure coding. */
   encodedSize(): bigint
   /** Returns the slabs that make up the object. */
@@ -135,6 +189,23 @@ export declare class PinnedObject {
 }
 
 export declare class Sdk {
+  /** Creates a sharing key. Attach objects to it with `Sdk.shareObject`. */
+  createSharingKey(description: string, expiresAt?: Date | undefined | null): Promise<SharingKey>
+  /** Lists the account's sharing keys, most recently created first. */
+  sharingKeys(offset: number, limit: number): Promise<Array<KeyRecord>>
+  /** Fetches the indexer's record for a key, including its counts. */
+  sharingKey(key: SharingKey): Promise<KeyRecord>
+  /**
+   * Attaches an object to a sharing key, re-sealing its encryption keys under
+   * the key so recipients can decrypt it.
+   */
+  shareObject(key: SharingKey, object: PinnedObject): Promise<void>
+  /** Lists and decrypts the objects attached to a sharing key. */
+  sharedObjects(key: SharingKey, offset: number, limit: number): Promise<Array<PinnedObject>>
+  /** Detaches an object from a sharing key. */
+  unshareObject(key: SharingKey, id: string): Promise<void>
+  /** Revokes a sharing key, deleting it and detaching all of its objects. */
+  revokeSharingKey(key: SharingKey): Promise<void>
   /** Returns the application key used by the SDK. */
   appKey(): AppKey
   /**
@@ -164,8 +235,8 @@ export declare class Sdk {
    * of the object's data.
    */
   download(object: PinnedObject, options?: DownloadOptions | undefined | null): ReadableStream
-  /** Returns a list of all usable hosts. */
-  hosts(): Promise<Array<Host>>
+  /** Returns a list of usable hosts, optionally filtered by a query. */
+  hosts(query?: HostQuery | undefined | null): Promise<Array<Host>>
   /** Returns object events from the indexer for syncing. */
   objectEvents(cursor: ObjectsCursor | undefined | null, limit: number): Promise<Array<ObjectEvent>>
   /** Updates the metadata of an object stored in the indexer. */
@@ -181,13 +252,58 @@ export declare class Sdk {
   /** Returns the current account. */
   account(): Promise<Account>
   /** Creates a signed URL for sharing an object. */
-  shareObject(object: PinnedObject, validUntil: Date): string
+  objectShareUrl(object: PinnedObject, validUntil: Date): string
   /** Retrieves a shared object from a signed URL. */
-  sharedObject(sharedUrl: string): Promise<PinnedObject>
+  objectFromShareUrl(sharedUrl: string): Promise<PinnedObject>
   /** Pins an object to the indexer. */
   pinObject(object: PinnedObject): Promise<void>
 }
 
+/**
+ * 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 declare class SharedSdk {
+  /**
+   * Connects to `indexer_url` as the recipient of the sharing key derived
+   * from `seed`, the 32-byte seed the key's owner handed out.
+   */
+  static connect(indexerUrl: string, seed: Buffer): Promise<SharedSdk>
+  /** Fetches the sharing key's stats from the indexer. */
+  stats(): Promise<KeyStats>
+  /** 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<Array<PinnedObject>>
+  /**
+   * Returns the hosts serving this key's objects, optionally filtered by a
+   * query. Mirrors `Sdk.hosts()` but is scoped to the sharing key, so the
+   * set is already limited to hosts holding its objects.
+   */
+  hosts(query?: HostQuery | undefined | null): Promise<Array<Host>>
+  /** Streams a shared object's data, paying hosts with the owner's tokens. */
+  download(object: PinnedObject, options?: DownloadOptions | undefined | null): ReadableStream
+}
+
+/**
+ * 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 declare class SharingKey {
+  /** The key's public half, which identifies it on the indexer. */
+  get publicKey(): string
+  /**
+   * The 32-byte seed a recipient needs to read the key's objects. Pair it
+   * with the indexer url in `SharedSdk.connect`.
+   */
+  seed(): Buffer
+  /** Imports a sharing key from the 32-byte seed its owner handed out. */
+  static fromSeed(seed: Buffer): SharingKey
+}
+
 /** An account registered on the indexer. */
 export interface Account {
   accountKey: string
@@ -203,7 +319,7 @@ export interface Account {
 /** The protocol used in a network address. */
 export declare const enum AddressProtocol {
   SiaMux = 'SiaMux',
-  Quic = 'Quic'
+  Quic = 'Quic',
 }
 
 /** Application info. */
@@ -239,6 +355,12 @@ export declare function encodedSize(size: bigint, dataShards: number, parityShar
 /** Generates a new BIP-39 12-word recovery phrase. */
 export declare function generateRecoveryPhrase(): string
 
+/** Geographic coordinates used to sort hosts by proximity. */
+export interface GeoLocation {
+  latitude: number
+  longitude: number
+}
+
 /** Information about a storage provider on the Sia network. */
 export interface Host {
   publicKey: string
@@ -249,6 +371,29 @@ export interface Host {
   goodForUpload: boolean
 }
 
+/** Query parameters for filtering hosts. */
+export interface HostQuery {
+  location?: GeoLocation
+  protocol?: AddressProtocol
+  country?: string
+  limit?: number
+  offset?: number
+}
+
+/**
+ * A snapshot of what a sharing key grants access to. The counts reflect the
+ * moment the record was fetched, not a live view.
+ */
+export interface KeyStats {
+  objectCount: bigint
+  objectSize: bigint
+  pinnedData: bigint
+  pinnedSize: bigint
+  expiresAt?: Date
+  createdAt: Date
+  updatedAt: Date
+}
+
 /** A network address of a storage provider on the Sia network. */
 export interface NetAddress {
   protocol: AddressProtocol
@@ -337,3 +482,12 @@ export interface UploadOptions {
 export declare function validateRecoveryPhrase(phrase: string): void
 
 export declare function initSia(): Promise<void>
+export declare function detectPrivateRelay(): Promise<boolean>
+/** Always false. Service worker streaming is for browser pages. */
+export declare function enableStreaming(options?: { workerUrl?: string; scope?: string; type?: 'classic' | 'module' }): Promise<boolean>
+/** For browser pages. In Node, `url` and `download` reject, and `sdk.download()` streams objects directly. */
+export declare function openStreams(sdk: object, credentials: { indexerUrl: string; appMeta: AppMetadata } | { indexerUrl: string; seed: string }): {
+  url(object: PinnedObject, options: { name: string; type?: string }): Promise<never>
+  download(object: PinnedObject, options: { name: string; type?: string }): Promise<never>
+  close(): void
+}

package/dist/next.d.ts

@@ -0,0 +1,3 @@
+declare function GET(): Response;
+
+export { GET };