Class SecretVaultBuilderClient

Client for performing builder operations on SecretVaults.

This client handles all builder-specific operations including registration, collection management, data operations, and query execution. It supports automatic handling of concealed data when configured with blindfold.

Hierarchy

SecretVaultBaseClient<NilDbBuilderClient>
- SecretVaultBuilderClient

Constructors

constructor

new SecretVaultBuilderClient(
options: SecretVaultBuilderOptions,
): SecretVaultBuilderClient
Parameters
- options: SecretVaultBuilderOptions
Returns SecretVaultBuilderClient
Overrides SecretVaultBaseClient<NilDbBuilderClient>.constructor
- Defined in src/builder.ts:205

Accessors

nodes

get nodes(): TClient[]
The array of underlying node clients for the cluster.

Returns TClient[]
Inherited from SecretVaultBaseClient.nodes
- Defined in src/base.ts:67

rootToken

get rootToken(): {}
Returns {}
- Defined in src/builder.ts:221

signer

get signer(): Signer
The signer used by this client for signing.

Returns Signer
Inherited from SecretVaultBaseClient.signer
- Defined in src/base.ts:74

Methods

createCollection

createCollection(
    body: {
        _id: string;
        name: string;
        schema: Record<string, unknown>;
        type: "standard" | "owned";
    },
    options?: { auth?: AuthContext },
): Promise<ByNodeName<string>>
Creates a new collection on all nodes.
Parameters
- body: {
      _id: string;
      name: string;
      schema: Record<string, unknown>;
      type: "standard" | "owned";
  }
- Optionaloptions: { auth?: AuthContext }
Returns Promise<ByNodeName<string>>
- Defined in src/builder.ts:328

createCollectionIndex

createCollectionIndex(
    collection: string,
    body: {
        collection: string;
        keys: Record<string, -1 | 1>[];
        name: string;
        ttl?: number;
        unique: boolean;
    },
    options?: { auth?: AuthContext },
): Promise<ByNodeName<string>>
Creates a new index on a collection.
Parameters
- collection: string
- body: {
      collection: string;
      keys: Record<string, -1 | 1>[];
      name: string;
      ttl?: number;
      unique: boolean;
  }
- Optionaloptions: { auth?: AuthContext }
Returns Promise<ByNodeName<string>>
- Defined in src/builder.ts:429

createQuery

createQuery(
    body: {
        _id: string;
        collection: string;
        name: string;
        pipeline: Record<string, unknown>[];
        variables: Record<string, { description?: string; path: string }>;
    },
    options?: { auth?: AuthContext },
): Promise<ByNodeName<string>>
Creates a new saved query on all nodes.
Parameters
- body: {
      _id: string;
      collection: string;
      name: string;
      pipeline: Record<string, unknown>[];
      variables: Record<string, { description?: string; path: string }>;
  }
- Optionaloptions: { auth?: AuthContext }
Returns Promise<ByNodeName<string>>
- Defined in src/builder.ts:572

createStandardData

createStandardData(
    body: { collection: string; data: Record<string, unknown>[] },
    options?: { auth?: AuthContext },
): Promise<
    ByNodeName<
        {
            data: {
                created: string[];
                errors: { document: unknown; error: string }[];
            };
        },
    >,
>
Creates one or more standard data documents in a collection.
Parameters
- body: { collection: string; data: Record<string, unknown>[] }
- Optionaloptions: { auth?: AuthContext }
Returns Promise<
    ByNodeName<
        {
            data: {
                created: string[];
                errors: { document: unknown; error: string }[];
            };
        },
    >,
>
- Defined in src/builder.ts:489

deleteBuilder

deleteBuilder(options?: { auth?: AuthContext }): Promise<ByNodeName<string>>
Deletes the builder and associated resources from all nodes.
Parameters
- Optionaloptions: { auth?: AuthContext }
Returns Promise<ByNodeName<string>>
- Defined in src/builder.ts:308

deleteCollection

deleteCollection(
collection: string,
options?: { auth?: AuthContext },
): Promise<ByNodeName<string>>
Deletes a collection its data from all nodes.
Parameters
- collection: string
- Optionaloptions: { auth?: AuthContext }
Returns Promise<ByNodeName<string>>
- Defined in src/builder.ts:408

deleteData

deleteData(
    body: { collection: string; filter: Record<string, unknown> },
    options?: { auth?: AuthContext },
): Promise<
    ByNodeName<{ data: { acknowledged: boolean; deletedCount: number } }>,
>
Deletes data from a collection based on a filter.
Parameters
- body: { collection: string; filter: Record<string, unknown> }
- Optionaloptions: { auth?: AuthContext }
Returns Promise<ByNodeName<{ data: { acknowledged: boolean; deletedCount: number } }>>
- Defined in src/builder.ts:747

deleteQuery

deleteQuery(
query: string,
options?: { auth?: AuthContext },
): Promise<ByNodeName<string>>
Deletes a saved query from all nodes.
Parameters
- query: string
- Optionaloptions: { auth?: AuthContext }
Returns Promise<ByNodeName<string>>
- Defined in src/builder.ts:602

dropCollectionIndex

dropCollectionIndex(
    collection: string,
    index: string,
    options?: { auth?: AuthContext },
): Promise<ByNodeName<string>>
Drops an index from a collection.
Parameters
- collection: string
- index: string
- Optionaloptions: { auth?: AuthContext }
Returns Promise<ByNodeName<string>>
- Defined in src/builder.ts:459

findData

findData(
    body: {
        collection: string;
        filter: Record<string, unknown>;
        pagination?: {
            limit: number;
            offset: number;
            sort?: Record<string, -1 | 1>;
        };
    },
    options?: { auth?: AuthContext },
): Promise<
    {
        data: Record<string, unknown>[];
        pagination: {
            limit: number;
            offset: number;
            sort?: Record<string, -1 | 1>;
            total: number;
        };
    },
>
Finds data in a collection, revealing concealed values if a key is configured.
Parameters
- body: {
      collection: string;
      filter: Record<string, unknown>;
      pagination?: {
          limit: number;
          offset: number;
          sort?: Record<string, -1 | 1>;
      };
  }
- Optionaloptions: { auth?: AuthContext }
Returns Promise<
    {
        data: Record<string, unknown>[];
        pagination: {
            limit: number;
            offset: number;
            sort?: Record<string, -1 | 1>;
            total: number;
        };
    },
>
- Defined in src/builder.ts:671

flushData

flushData(
collection: string,
options?: { auth?: AuthContext },
): Promise<ByNodeName<string>>
Deletes all data from a collection.
Parameters
- collection: string
- Optionaloptions: { auth?: AuthContext }
Returns Promise<ByNodeName<string>>
- Defined in src/builder.ts:776

getDid

getDid(): Promise<Did$1>
The DID of the signer associated with this client.

Returns Promise<Did$1>
Inherited from SecretVaultBaseClient.getDid
- Defined in src/base.ts:60

getId

getId(): Promise<string>
Returns Promise<string>
Inherited from SecretVaultBaseClient.getId
- Defined in src/base.ts:53

getQueries

getQueries(
    options?: {
        auth?: AuthContext;
        pagination?: {
            limit: number;
            offset: number;
            sort?: Record<string, -1 | 1>;
        };
    },
): Promise<
    {
        data: { _id: string; collection: string; name: string }[];
        pagination: {
            limit: number;
            offset: number;
            sort?: Record<string, -1 | 1>;
            total: number;
        };
    },
>
Retrieves a list of all saved queries.
Parameters
- Optionaloptions: {
      auth?: AuthContext;
      pagination?: {
          limit: number;
          offset: number;
          sort?: Record<string, -1 | 1>;
      };
  }
Returns Promise<
    {
        data: { _id: string; collection: string; name: string }[];
        pagination: {
            limit: number;
            offset: number;
            sort?: Record<string, -1 | 1>;
            total: number;
        };
    },
>
- Defined in src/builder.ts:525

getQuery

getQuery(
    query: string,
    options?: { auth?: AuthContext },
): Promise<
    ByNodeName<{ data: { _id: string; collection: string; name: string } }>,
>
Retrieves a single saved query by its id.
Parameters
- query: string
- Optionaloptions: { auth?: AuthContext }
Returns Promise<ByNodeName<{ data: { _id: string; collection: string; name: string } }>>
- Defined in src/builder.ts:551

readClusterInfo

readClusterInfo(): Promise<
    ByNodeName<
        {
            build: { commit: string; time: string; version: string };
            maintenance: { active: boolean; started_at: string };
            public_key: string;
            started: string;
            url: string;
        },
    >,
>
Retrieves information about each node in the cluster.

Returns Promise<
    ByNodeName<
        {
            build: { commit: string; time: string; version: string };
            maintenance: { active: boolean; started_at: string };
            public_key: string;
            started: string;
            url: string;
        },
    >,
>
Inherited from SecretVaultBaseClient.readClusterInfo
- Defined in src/base.ts:81

readCollection

readCollection(
    collection: string,
    options?: { auth?: AuthContext },
): Promise<
    {
        data: {
            _id: string;
            count: number;
            first_write: string;
            indexes: {
                key: Record<string, string | number>;
                name: string;
                unique: boolean;
                v: number;
            }[];
            last_write: string;
            schema: Record<string, unknown>;
            size: number;
        };
    },
>
Reads the metadata for a single collection.
Parameters
- collection: string
- Optionaloptions: { auth?: AuthContext }
Returns Promise<
    {
        data: {
            _id: string;
            count: number;
            first_write: string;
            indexes: {
                key: Record<string, string | number>;
                name: string;
                unique: boolean;
                v: number;
            }[];
            last_write: string;
            schema: Record<string, unknown>;
            size: number;
        };
    },
>
- Defined in src/builder.ts:382

readCollections

readCollections(
    options?: {
        auth?: AuthContext;
        pagination?: {
            limit: number;
            offset: number;
            sort?: Record<string, -1 | 1>;
        };
    },
): Promise<
    {
        data: { id: string; name: string; type: "standard"
        | "owned" }[];
        pagination: {
            limit: number;
            offset: number;
            sort?: Record<string, -1 | 1>;
            total: number;
        };
    },
>
Reads a list of all collections from the cluster.
Parameters
- Optionaloptions: {
      auth?: AuthContext;
      pagination?: {
          limit: number;
          offset: number;
          sort?: Record<string, -1 | 1>;
      };
  }
Returns Promise<
    {
        data: { id: string; name: string; type: "standard"
        | "owned" }[];
        pagination: {
            limit: number;
            offset: number;
            sort?: Record<string, -1 | 1>;
            total: number;
        };
    },
>
- Defined in src/builder.ts:352

readProfile

readProfile(
    options?: { auth?: AuthContext },
): Promise<
    {
        data: {
            _created: string;
            _id: string;
            _updated: string;
            collections: string[];
            name: string;
            queries: string[];
        };
    },
>
Reads the builder's profile from the cluster.
Parameters
- Optionaloptions: { auth?: AuthContext }
Returns Promise<
    {
        data: {
            _created: string;
            _id: string;
            _updated: string;
            collections: string[];
            name: string;
            queries: string[];
        };
    },
>
- Defined in src/builder.ts:263

readQueryRunResults

readQueryRunResults(
    runs: ByNodeName<Uuid>,
    options?: { auth?: AuthContext },
): Promise<
    ByNodeName<
        {
            data: {
                _id: string;
                completed?: string;
                errors?: string[];
                query: string;
                result?: unknown;
                started?: string;
                status: "error"
                | "pending"
                | "running"
                | "complete";
            };
            pagination?: { limit: number; offset: number; total: number };
        },
    >,
>
Reads the results of a completed query run from each node.
Parameters
- runs: ByNodeName<Uuid>
- Optionaloptions: { auth?: AuthContext }
Returns Promise<
    ByNodeName<
        {
            data: {
                _id: string;
                completed?: string;
                errors?: string[];
                query: string;
                result?: unknown;
                started?: string;
                status: "error"
                | "pending"
                | "running"
                | "complete";
            };
            pagination?: { limit: number; offset: number; total: number };
        },
    >,
>
- Defined in src/builder.ts:651

refreshRootToken

refreshRootToken(): Promise<void>
Fetches a new root NUC token from the configured nilAuth server.

Returns Promise<void>
- Defined in src/builder.ts:231

register

register(body: { did: string; name: string }): Promise<ByNodeName<string>>
Registers the builder with all nodes in the cluster.
Parameters
- body: { did: string; name: string }
Returns Promise<ByNodeName<string>>
- Defined in src/builder.ts:252

runQuery

runQuery(
body: { _id: string; variables: Record<string, unknown> },
options?: { auth?: AuthContext },
): Promise<ByNodeName<{ data: string }>>
Starts a query execution job.
Parameters
- body: { _id: string; variables: Record<string, unknown> }
- Optionaloptions: { auth?: AuthContext }
Returns Promise<ByNodeName<{ data: string }>>
- Defined in src/builder.ts:623

subscriptionStatus

subscriptionStatus(): Promise<{}>
Checks subscription status by the builder's Did.

Returns Promise<{}>
- Defined in src/builder.ts:245

tailData

tailData(
collection: string,
options?: { auth?: AuthContext; limit?: number },
): Promise<{ data: Record<string, unknown>[] }>
Reads the last N documents from a collection, revealing concealed values if a key is configured.
Parameters
- collection: string
- Optionaloptions: { auth?: AuthContext; limit?: number }
Returns Promise<{ data: Record<string, unknown>[] }>
- Defined in src/builder.ts:797

updateBuilderProfile

updateBuilderProfile(
body: { name: string },
options?: { auth?: AuthContext },
): Promise<ByNodeName<string>>
Updates the builder's profile on all nodes.
Parameters
- body: { name: string }
- Optionaloptions: { auth?: AuthContext }
Returns Promise<ByNodeName<string>>
- Defined in src/builder.ts:284

updateData

updateData(
    body: {
        collection: string;
        filter: Record<string, unknown>;
        update: Record<string, unknown>;
    },
    options?: { auth?: AuthContext },
): Promise<
    ByNodeName<
        {
            data: {
                acknowledged: boolean;
                matched: number;
                modified: number;
                upserted: number;
                upserted_id: string
                | null;
            };
        },
    >,
>
Updates documents in a collection, concealing the update payload if a key is configured.
Parameters
- body: {
      collection: string;
      filter: Record<string, unknown>;
      update: Record<string, unknown>;
  }
- Optionaloptions: { auth?: AuthContext }
Returns Promise<
    ByNodeName<
        {
            data: {
                acknowledged: boolean;
                matched: number;
                modified: number;
                upserted: number;
                upserted_id: string
                | null;
            };
        },
    >,
>
- Defined in src/builder.ts:714

`Static`from

from(
    options: {
        blindfold?: BlindfoldFactoryConfig;
        dbs: string[];
        nilauthClient: NilauthClient;
        rootToken?: string | {};
        signer: Signer;
    },
): Promise<SecretVaultBuilderClient>

Creates and initializes a new SecretVaultBuilderClient instance.

Parameters

options: {
    blindfold?: BlindfoldFactoryConfig;
    dbs: string[];
    nilauthClient: NilauthClient;
    rootToken?: string | {};
    signer: Signer;
}

Returns Promise<SecretVaultBuilderClient>

Example

// Basic instantiation with an auto-generated key
const builderClient = await SecretVaultBuilderClient.from({
  signer: Signer.generate(),
  nilauthClient,
  dbs: ["http://localhost:40081", "http://localhost:40082"],
});

Example

// Advanced: Using a custom signer from a browser wallet
import { Signer } from "@nillion/nuc";

// Assumes window.ethereum is available from a browser wallet like MetaMask
const customSigner = await Signer.fromEip1193Provider(window.ethereum);

const clientWithSigner = await SecretVaultBuilderClient.from({
  signer: customSigner,
  nilauthClient,
  dbs: ["http://localhost:40081", "http://localhost:40082"],
});

Class SecretVaultBuilderClient

Hierarchy

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns SecretVaultBuilderClient

Accessors

nodes

Returns TClient[]

rootToken

Returns {}

signer

Returns Signer

Methods

createCollection

Parameters

Returns Promise<ByNodeName<string>>

createCollectionIndex

Parameters

Returns Promise<ByNodeName<string>>

createQuery

Parameters

Returns Promise<ByNodeName<string>>

createStandardData

Parameters

Returns Promise< ByNodeName< { data: { created: string[]; errors: { document: unknown; error: string }[]; }; }, >,>

deleteBuilder

Parameters

Returns Promise<ByNodeName<string>>

deleteCollection

Parameters

Returns Promise<ByNodeName<string>>

deleteData

Parameters

Returns Promise<ByNodeName<{ data: { acknowledged: boolean; deletedCount: number } }>>

deleteQuery

Parameters

Returns Promise<ByNodeName<string>>

dropCollectionIndex

Parameters

Returns Promise<ByNodeName<string>>

findData

Parameters

Returns Promise< { data: Record<string, unknown>[]; pagination: { limit: number; offset: number; sort?: Record<string, -1 | 1>; total: number; }; },>

flushData

Parameters

Returns Promise<ByNodeName<string>>

getDid

Returns Promise<Did$1>

getId

Returns Promise<string>

getQueries

Parameters

Returns Promise< { data: { _id: string; collection: string; name: string }[]; pagination: { limit: number; offset: number; sort?: Record<string, -1 | 1>; total: number; }; },>

getQuery

Parameters

Returns Promise<ByNodeName<{ data: { _id: string; collection: string; name: string } }>>

readClusterInfo

Returns Promise< ByNodeName< { build: { commit: string; time: string; version: string }; maintenance: { active: boolean; started_at: string }; public_key: string; started: string; url: string; }, >,>

readCollection

Parameters

Returns Promise< { data: { _id: string; count: number; first_write: string; indexes: { key: Record<string, string | number>; name: string; unique: boolean; v: number; }[]; last_write: string; schema: Record<string, unknown>; size: number; }; },>

readCollections

Parameters

Returns Promise< { data: { id: string; name: string; type: "standard" | "owned" }[]; pagination: { limit: number; offset: number; sort?: Record<string, -1 | 1>; total: number; }; },>

readProfile

Parameters

Returns Promise< { data: { _created: string; _id: string; _updated: string; collections: string[]; name: string; queries: string[]; }; },>

readQueryRunResults

Parameters

Returns Promise< ByNodeName< { data: { _id: string; completed?: string; errors?: string[]; query: string; result?: unknown; started?: string; status: "error" | "pending" | "running" | "complete"; }; pagination?: { limit: number; offset: number; total: number }; }, >,>

refreshRootToken

Returns Promise<void>

register

Parameters

Returns Promise<ByNodeName<string>>

Returns Promise<
ByNodeName<
{
data: {
created: string[];
errors: { document: unknown; error: string }[];
};
},
>,
>

Returns Promise<
{
data: Record<string, unknown>[];
pagination: {
limit: number;
offset: number;
sort?: Record<string, -1 | 1>;
total: number;
};
},
>

Returns Promise<
{
data: { _id: string; collection: string; name: string }[];
pagination: {
limit: number;
offset: number;
sort?: Record<string, -1 | 1>;
total: number;
};
},
>

Returns Promise<
ByNodeName<
{
build: { commit: string; time: string; version: string };
maintenance: { active: boolean; started_at: string };
public_key: string;
started: string;
url: string;
},
>,
>

Returns Promise<
{
data: {
_id: string;
count: number;
first_write: string;
indexes: {
key: Record<string, string | number>;
name: string;
unique: boolean;
v: number;
}[];
last_write: string;
schema: Record<string, unknown>;
size: number;
};
},
>

Returns Promise<
{
data: { id: string; name: string; type: "standard"
| "owned" }[];
pagination: {
limit: number;
offset: number;
sort?: Record<string, -1 | 1>;
total: number;
};
},
>

Returns Promise<
{
data: {
_created: string;
_id: string;
_updated: string;
collections: string[];
name: string;
queries: string[];
};
},
>

Returns Promise<
ByNodeName<
{
data: {
_id: string;
completed?: string;
errors?: string[];
query: string;
result?: unknown;
started?: string;
status: "error"
| "pending"
| "running"
| "complete";
};
pagination?: { limit: number; offset: number; total: number };
},
>,
>

Returns Promise<
ByNodeName<
{
data: {
acknowledged: boolean;
matched: number;
modified: number;
upserted: number;
upserted_id: string
| null;
};
},
>,
>

`Static`from