@stacks/storage

@stacks/storage

Store and fetch files with Gaia, the decentralized storage system.

Installation

npm install @stacks/storage

Usage

Initiate a session

Users must authenticate to an app before the storage package will work to save or retrieve data on their behalf.

See also authentication guide using connect for web apps

The storage capabilities will work in cases userSession.isUserSignedIn() returns true

Initiating a storage client

import { UserSession, AppConfig } from '@stacks/auth';
import { Storage } from '@stacks/storage';

const privateKey = '896adae13a1bf88db0b2ec94339b62382ec6f34cd7e2ff8abae7ec271e05f9d8';
const appConfig = new AppConfig();
const userSession = new UserSession({ appConfig });
userSession.store.getSessionData().userData = <any> {
  appPrivateKey: privateKey,
};
const storage = new Storage({ userSession });

Note that you can also use an existing userSession object created during the authentication process.

Put file

const myData = JSON.stringify({
  hello: "world",
  num: 1
});

const fileUrl = await storage.putFile('my_data.json', myData);
// You'll need to save an entirely new string of modified data using putFile with the same fileName every time you want to update a record. 
// There is no separate update method.

Store data at a different path

const fileUrl = await storage.putFile('path/my_data.json', myData);

Put file with options

const putFileOptions = {
  // override the default content type
  contentType: 'application/json', 
  // override encrypting data by default
  // you can also set encrypt to a private key to specify a custom encryption key
  encrypt: false, 
  // ignore automatic conflict prevention using etags
  dangerouslyIgnoreEtag: true
}

const fileUrl = await storage.putFile('my_data.json', myData, putFileOptions);

Get file

const fileContent = await storage.getFile('my_data.json');
console.log(fileContent);

Get file with options

const getFileOptions = {
  decrypt: false,
  // by default files stored are signed and can be verified for authenticity
  verify: false
}

const fileContent = await storage.getFile('my_data.json', getFileOptions);
console.log(fileContent);

Get file for other user

// Retrieve public data saved by users other than the one with the active session
// User should have registered username via BNS
const options = {
  username: 'yukan.id',
  // app: 'https://example.org',
  decrypt: false,
};
// Set an additional app property within options to retrieve data for a user as saved by an app hosted at a separate domain

const fileContent = await storage.getFile('my_data.json', options);
console.log(fileContent);

Delete file

await storage.deleteFile('my_data.json');

Delete the file and the corresponding signature file if signed

await storage.deleteFile('my_data.json', { wasSigned: true });

List file

List all files in the user's Gaia hub

const files: Promise<string | undefined | ArrayBuffer | null>[] = [];
const options = { decrypt: false };
await storage.listFiles((filename: string) => {
  if (filename === 'my_data.json') {
    files.push(storage.getFile(filename, options));
    // return false to stop iterating through files
    return false;
  } else {
    // return true to continue iterating
    return true;
  }
});
const fileContents = await Promise.all(files);

Changelog

7.0.4 (2025-02-03)

Bug Fixes

• Add byte length override for transfer fee estimates (#1763) (a789994)
• regression in 'NoEstimateAvailable' check (#1785) (a079a74)
• use correct types for postConditions (#1784) (1d7d280)