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.

setAssetTokenStore​

Set or update an access token for an asset.

function setAssetTokenStore(params: SetAssetTokenStoreParams): void;

📦 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.
  • token: The token to apply to the asset. Setting undefined removes the protection and makes the asset public.

Returns:​

  • void

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.

Access Keys​

The following functions allow you to inspect and assert the access keys of your Satellite.

getAccessKeys​

Retrieves all access keys of the Satellite.

function getAccessKeys(): AccessKeys;

📦 Import from @junobuild/functions/sdk

Returns:​

  • AccessKeys: The list of all access keys.

Throws:​

  • ZodError if the returned value does not match the expected schema.

getAdminAccessKeys​

Retrieves only the admin access keys of the Satellite.

function getAdminAccessKeys(): AccessKeys;

📦 Import from @junobuild/functions/sdk

Returns:​

  • AccessKeys: The list of admin access keys.

Throws:​

  • ZodError if the returned value does not match the expected schema.

isWriteAccessKey​

Checks if the given id is a non-expired access key with admin or write scope.

function isWriteAccessKey(params: AccessKeyCheckParams): boolean;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
  • id: The principal to check (RawUserId or UserId).
  • accessKeys: The list of access keys to verify against.

Returns:​

  • boolean: Whether the id is an access key with write permission.

Throws:​

  • ZodError if any input does not match the expected schema.

isValidAccessKey​

Checks if the given id is a non-expired access key regardless of scope (admin, write, or submit).

function isValidAccessKey(params: AccessKeyCheckParams): boolean;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
  • id: The principal to check (RawUserId or UserId).
  • accessKeys: The list of access keys to verify against.

Returns:​

  • boolean: Whether the id is a recognized access key.

Throws:​

  • ZodError if any input does not match the expected schema.

isAdminController​

Checks if the given id is an admin access key and a controller known by the Internet Computer.

function isAdminController(params: AccessKeyCheckParams): boolean;

📦 Import from @junobuild/functions/sdk

Parameters:​

  • params: An object containing:
  • id: The principal to check (RawUserId or UserId).
  • accessKeys: The list of access keys to verify against.

Returns:​

  • boolean: Whether the id is an admin and a controller of the Satellite.

Throws:​

  • ZodError if any input does not match the expected schema.

Guards​

The following guard functions can be used to validate the caller in your custom serverless functions.

callerIsAdmin​

Guards that the caller is an admin access key of this satellite. Admin access keys have full management privileges and never expire.

function callerIsAdmin(): void;

📦 Import from @junobuild/functions/sdk

Returns:​

  • void

Throws:​

  • ZodError if the caller is not an admin access key.

callerHasWritePermission​

Guards that the caller has write permission. Admin and editor access keys pass; submitter access keys do not.

function callerHasWritePermission(): void;

📦 Import from @junobuild/functions/sdk

Returns:​

  • void

Throws:​

  • ZodError if the caller does not have write permission.

callerIsAccessKey​

Guards that the caller is any recognized access key of this satellite. Accepts admin, editor, and submitter access keys alike.

function callerIsAccessKey(): void;

📦 Import from @junobuild/functions/sdk

Returns:​

  • void

Throws:​

  • ZodError if the caller is not a recognized access key.