API Reference

This document provides a detailed reference for the public API of the Lens SDK, primarily focusing on the LensService class. The LensService is the sole intended entry point for developers building applications with the SDK.

LensService

The LensService class provides a high-level, asynchronous interface for all SDK functionalities. It manages the Peerbit client, the Site program lifecycle, and all user-facing operations.

Constructor

new LensService(options?: {
  peerbit?: ProgramClient;
  debug?: boolean;
  customPrefix?: string;
  identity?: Identity<Secp256k1PublicKey>;
})

Initializes a new instance of the service.

Lifecycle Methods

These methods control the connection to the Peerbit network and the active Site program.

init()

init(directory?: string): Promise<void>

Initializes and starts a new, internally managed Peerbit client. This method must be called before any other operations if the service was not constructed with an external client.

stop()

stop(): Promise<void>

Gracefully shuts down the service, closing the active Site and stopping the Peerbit client (if internally managed).

openSite()

openSite(
  siteOrAddress: Site | string, 
  options?: { siteArgs?: SiteArgs, federate?: boolean }
): Promise<void>

Opens a Site program, making it the active context for all subsequent API calls.

Account and Status Methods

Methods for retrieving information about the current user.

getAccountStatus()

getAccountStatus(): Promise<AccountStatusResponse>

Determines the full permission status of the current active identity (custom wallet or default node identity) for the active Site. This is the primary method for fetching the necessary information to render a user interface tailored to their capabilities.

interface AccountStatusResponse {
  isAdmin: boolean;      // True if the user is a top-level administrator
  roles: string[];       // An array of role names assigned to the user (e.g., ["moderator", "member"])
  permissions: string[]; // A flattened, unique list of all permissions granted by the user's roles
}

API Input Types

To simplify interactions, the LensService uses two primary input patterns for creating and editing documents.

• AddInput<T>: This is used for creating new documents (e.g., in addRelease). The type AddInput<T> is an alias for just T. You provide only the core data properties for the document you want to create. The LensService is responsible for automatically adding the required id, postedBy, and siteAddress fields.

• EditInput<T>: This is used for updating existing documents (e.g., in editRelease). This type is an alias for T & ImmutableProps. You must provide the full data for the document, including the id, postedBy, and siteAddress of the existing document. The service will verify that the immutable properties (postedBy and siteAddress) have not been changed.

Content Management (Releases)

Methods for creating and managing the primary content type, Release.

addRelease()

addRelease(data: AddInput<ReleaseData>): Promise<HashResponse>

Creates and saves a new Release document. Requires the user to have a role with the release:create permission (e.g., Member, Moderator, Admin).

editRelease()

editRelease(data: EditInput<ReleaseData>): Promise<HashResponse>

Updates an existing Release. The required permission depends on the action:

• A user with the release:edit:own permission can edit a release where they are the postedBy.
• A user with the release:edit:any permission can edit any release.

Updates an existing Release. The data object must include the id. Requires ADMIN privileges.

deleteRelease()

deleteRelease(id: string): Promise<IdResponse>

Deletes a Release by its ID. Requires the release:delete permission (e.g., Moderator, Admin).

getRelease()

getRelease(id: string): Promise<WithContext<Release> | undefined>

Retrieves a single Release by its ID.

getReleases()

getReleases(options?: SearchOptions): Promise<WithContext<Release>[]>

Retrieves an array of Release documents.

Featured Content Management

Methods for managing FeaturedRelease entries. These operations require a role with the featured:manage permission (e.g., Moderator, Admin).

addFeaturedRelease()

addFeaturedRelease(data: AddInput<FeaturedReleaseData>): Promise<HashResponse>

Creates a FeaturedRelease to highlight an existing Release.

editFeaturedRelease()

editFeaturedRelease(data: EditInput<FeaturedReleaseData>): Promise<HashResponse>

Updates an existing FeaturedRelease. The id must be present, and core properties (postedBy, siteAddress) cannot be changed.

deleteFeaturedRelease()

deleteFeaturedRelease(id:string): Promise<IdResponse>

Deletes a FeaturedRelease by its ID.

(Methods getFeaturedRelease and getFeaturedReleases follow the same pattern as their Release counterparts.)

Content Category Management

Methods for managing ContentCategory documents. These operations require a role with the category:manage permission (e.g., Moderator, Admin).

addContentCategory()

addContentCategory(data: AddInput<ContentCategoryData>): Promise<HashResponse>

Creates a new ContentCategory. The categoryId must be unique.

editContentCategory()

editContentCategory(data: EditInput<ContentCategoryData>): Promise<HashResponse>

Updates an existing ContentCategory. The service will reject the update if immutable fields (postedBy, siteAddress, categoryId) are changed.

deleteContentCategory()

deleteContentCategory(id: string): Promise<IdResponse>

Deletes a ContentCategory by its ID.

getContentCategory()

getContentCategory(id: string): Promise<WithContext<ContentCategory> | undefined>

Retrieves a single ContentCategory by its ID.

getContentCategories()

getContentCategories(options?: SearchOptions): Promise<WithContext<ContentCategory>[]>

Retrieves an array of all ContentCategory documents.

Federation (Subscription) Management

Methods for managing federation relationships. These operations require a role with the subscription:manage permission (e.g., Moderator, Admin).

addSubscription()

addSubscription(data: AddInput<SubscriptionData>): Promise<HashResponse>

Subscribes to another Site, initiating federation.

deleteSubscription()

deleteSubscription(data: { id?: string; to?: string }): Promise<IdResponse>

Unsubscribes from a Site, stopping federation and purging its content.

getSubscriptions()

getSubscriptions(options?: SearchOptions): Promise<Subscription[]>

Retrieves a list of all current Subscription documents.

Access Control Management

Methods for managing user permissions on the active Site. These operations are privileged and can only be performed by an Administrator.

addAdmin()

addAdmin(publicKey: string | PublicSignKey): Promise<BaseResponse>

Promotes another user to be a full Administrator, adding them to the site’s root TrustedNetwork.

assignRole()

assignRole(publicKey: string | PublicSignKey, roleId: string): Promise<BaseResponse>

Assigns a specific role to a user.

revokeRole()

revokeRole(publicKey: string | PublicSignKey, roleId: string): Promise<BaseResponse>

Revokes a specific role from a user.

Common Response Objects

Most methods in the LensService return one of the following standardized response objects to ensure consistent error handling and feedback.

BaseResponse

The simplest response object, indicating only success or failure.

IdResponse

Extends BaseResponse to include the unique ID of the document that was affected.

HashResponse

Extends IdResponse to also include the cryptographic hash of the operation’s log entry, which can be used for verification.