@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.0 (2024-10-25)

⚠ BREAKING CHANGES

See full list of changes at MIGRATION.md

• Update Cl.serialize to return string instead of bytes (3d4052b)
• Rename StacksTransaction to StacksTransactionWire (fe74e87)
• Update StacksTransaction constructor to options object (2b15209)
• Make StacksTransaction.serialize() return a hex-string instead of bytes (b563a2d)
• Rename message types (3d8b2dc)
• Remove BN.js compatibility (ddd8dde)
• Rename more types to use "Wire" suffix (221633a)
• Remove wrapper type for message signatures (bf08b46)
• Rename networking/fetch methods to include fetch prefix (463176a)
• Update post-condition representation to human readable types (a7cff36)
• Remove optional anchor mode from transaction options (2bec7ae)
• Remove wrapped private key type (a4e86ce)
• Change clarity types to be human readable (edad3b4)
• Update to new network object (57369cc)

Features

• Add origin post-condition principals (ccc79b3)
• Add Address namespace (1291687)
• Add STX unit helper methods (94f6c6b)
• Add postConditionToHex helper (e224b0e)
• Add Cl.parse Clarity value parser (b9f8775)
• Add non-sequential multi-sig support (and fix legacy multi-sig bugs) (879263c)
• Add serialization helpers for transaction (2c57ea4)
• Allow 0x prefix in hexToBytes helper (33ca645)
• Use API for nonce detection if available (855ca69)
• Add new api package (9cf8a75)
• Cleanup common files (8316766)

Bug Fixes

• Update post conditions input in transactions (d005d19)
• Switch to a network and client param solution (e7370a0)
• Fix string parsing in structured signature decode (9760497)
• Remove legacy methods (6cece09)
• Generate compressed private keys by default (badc4bf)
• Compressing private key should ensure string format (350e1fa)
• Move more helper functions to take network parameter (b8cbde2)
• Remove signed option for intToBigInt (1a3cc2f)
• Allow .appendOrigin to be used with unwrapped public key (9c4a951)
• Improve address helper functions (e53528b)
• Allow network name in more helper functions (3d92cc7)
• Add .bootAddress to network objects (9993519)
• Disable legacy triplesec support for mnemonic encryption (9b98e44)
• Remove legacy CLI methods (3c373e1)
• Update remaining packages for api (2378096)
• Consolidate poxaddress return types (0dbe0db)