Skip to main content

SDK

The following functions are provided to help you work with document and asset data inside your Satellite. They are part of the tools available when writing serverless functions in TypeScript and support common tasks such as interacting with the datastore, storage, and custom hook logic.

📦 Library

The SDK is provided by the @junobuild/functions library.

To add it to your project:

npm i @junobuild/functions

You have to follow the pace of the Juno release to ensure compatibility. Refer to the maintenance guide for instructions.

Datastore​

The following functions can be used to manage documents within the Datastore from your serverless functions.

setDocStore​

Sets a document in a collection’s of the datastore. Use this to insert or update document data.

function setDocStore(params: SetDocStoreParams): void;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing the following fields:
    • caller: The caller initiating the operation (RawUserId or UserId).
    • collection: The name of the collection where the document will be stored.
    • key: The key identifying the document.
    • doc: The document content including:
      • data: A Uint8Array produced by encodeDocData.
      • description (optional): A short description linked with the document.
      • version (optional if new): An expected version number to prevent overwrite.

Returns:​

  • void

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation is rejected by the Satellite (e.g. due to a failed assertion or validation error).

getDocStore​

Retrieves a document from the datastore.

function getDocStore(params: GetDocStoreParams): OptionDoc;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
    • caller: The caller requesting the document (RawUserId or UserId).
    • collection: The collection containing the document.
    • key: The key identifying the document.

Returns:​

  • OptionDoc: The document if found, or undefined.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if retrieval fails.

listDocsStore​

Lists documents in a collection using optional filters, pagination, and sorting.

function listDocsStore(params: ListDocsStoreParams): ListResults<Doc>;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
    • caller: The caller initiating the request (RawUserId or UserId).
    • collection: The collection to list documents from.
    • params: A ListParams object with pagination, filtering, or sorting options.

Returns:​

  • ListResults<Doc>: Matching documents and pagination metadata.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if listing fails.

countDocsStore​

Counts documents matching filter criteria.

function countDocsStore(params: CountDocsStoreParams): bigint;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
    • caller: The caller initiating the operation.
    • collection: The collection to count documents in.
    • params: A ListParams object with filter and pagination options.

Returns:​

  • bigint: Number of documents matching the filter.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.

countCollectionDocsStore​

Counts the total number of documents in a collection.

function countCollectionDocsStore(
  params: CountCollectionDocsStoreParams
): bigint;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
    • collection: The collection to count documents in.

Returns:​

  • bigint: The total number of documents.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.

deleteDocStore​

Deletes a document from the datastore.

function deleteDocStore(params: DeleteDocStoreParams): DocContext<OptionDoc>;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
    • caller: The caller initiating the deletion (RawUserId or UserId).
    • collection: The collection where the document is stored.
    • key: The key identifying the document.
    • doc: The document deletion metadata including:
    • version: The expected version of the document.

Returns:​

  • DocContext<OptionDoc>: Includes the key, collection, and optionally the previous document data.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if validation fails or the document cannot be deleted.

deleteDocsStore​

Deletes all documents in a specific collection.

function deleteDocsStore(params: DeleteDocsStoreParams): void;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
    • collection: The collection to delete.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.

deleteFilteredDocsStore​

Deletes documents matching filter criteria.

function deleteFilteredDocsStore(
  params: DeleteFilteredDocsStoreParams
): DocContext<OptionDoc>[];

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
    • caller: The caller initiating the deletion.
    • collection: The collection to target.
    • params: A ListParams object with filter and pagination options.

Returns:​

  • DocContext<OptionDoc>[]: Context for each deleted document.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.

Storage​

The following functions can be used to manage assets within the Storage from your serverless functions.

setAssetHandler​

Sets or updates an asset using identity encoding (no compression).

function setAssetHandler(params: SetAssetHandlerParams): void;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing: - key: An object identifying the asset, including: - name: The asset filename (e.g., logo.png). - full_path: The asset path (e.g., /images/logo.png). - collection: The collection it belongs to. - owner: The caller principal. - token (optional): An access token if required. - description (optional): A short description. - content: A Uint8Array representing the raw content of the asset. - headers: An array of header fields to store with the asset.

Returns:​

  • void

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.

getAssetStore​

Retrieves an asset from the Storage.

function getAssetStore(params: GetAssetStoreParams): OptionAsset;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
  • caller: The identity requesting the asset (RawUserId or UserId).
  • collection: The collection name.
  • full_path: The asset path.

Returns:​

  • OptionAsset: The asset if found, or undefined.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.

listAssetsStore​

Lists assets in a collection without their content.

function listAssetsStore(
  params: ListAssetsStoreParams
): ListResults<AssetNoContent>;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
  • caller: The identity making the request.
  • collection: The collection name.
  • params: A ListParams object to filter, sort, or paginate.

Returns:​

  • ListResults<AssetNoContent>: Matching assets without content chunks.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.

countCollectionAssetsStore​

Counts all assets in a collection.

function countCollectionAssetsStore(
  params: CountCollectionAssetsStoreParams
): bigint;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
  • collection: The collection name.

Returns:​

  • bigint: Number of assets in the collection.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.

countAssetsStore​

Counts assets in a collection matching filter criteria.

function countAssetsStore(params: CountAssetsStoreParams): bigint;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
  • caller: The identity making the request.
  • collection: The collection name.
  • params: A ListParams object to filter the count.

Returns:​

  • bigint: Number of matching assets.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.

deleteAssetStore​

Deletes a single asset from the Storage.

function deleteAssetStore(params: DeleteAssetStoreParams): OptionAsset;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
  • caller: The identity initiating the deletion.
  • collection: The collection name.
  • full_path: The asset path to delete.

Returns:​

  • OptionAsset: The deleted asset, or undefined.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.

deleteAssetsStore​

Deletes all assets in a collection.

function deleteAssetsStore(params: DeleteAssetsStoreParams): void;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
  • collection: The collection to delete.

Returns:​

  • void

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.

deleteFilteredAssetsStore​

Deletes assets matching filters in a collection.

function deleteFilteredAssetsStore(
  params: DeleteFilteredAssetsStoreParams
): OptionAsset[];

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
  • caller: The identity initiating the operation.
  • collection: The collection name.
  • params: A ListParams object to define the filters.

Returns:​

  • OptionAsset[]: List of deleted assets.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.

getContentChunksStore​

Retrieves a specific chunk of an asset.

function getContentChunksStore(
  params: GetContentChunksStoreParams
): Blob | undefined;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
  • encoding: The AssetEncoding to retrieve from.
  • chunk_index: The index of the chunk (starting from 0).
  • memory: Either Heap or Stable.

Returns:​

  • Blob | undefined: The content chunk if found.

Throws:​

  • ZodError if the input schema is invalid.
  • Error if the operation fails.