folders

client.folders lists a folder’s index and searches across folder indexes already opened on the device.

list

list opens the key domain’s folder index. It gets one decision and one access event. The SDK confirms the index is up to date before it returns it.

TypeScript

list(folder: Locator): Promise<Decided<Listing>>

Swift

func list(_ folder: Locator) async throws -> Decided<Listing>

Kotlin

suspend fun list(folder: Locator): Decided<Listing>

Parameters

Name	Type	Description
folder	Locator	The folder to list.

Returns: Decided<Listing>: on allow, the folder’s entries.

Records: View, on the folder index.

Errors: locked, no-session, unreachable, storage-unreachable, container-invalid, trust-failed.

search

search opens the folder index of every key domain in the person’s data scope, or of the datasets named. Each index open is its own decision. The SDK then searches the decrypted indexes on the device. The access event records the indexes opened, never the query. A result is a locator. Opening it is an open of its own.

TypeScript

search(query: SearchQuery, scope?: { datasets?: string[] }): Promise<SearchResult>

Swift

func search(_ query: SearchQuery, datasets: [String]? = nil) async throws -> SearchResult

Kotlin

suspend fun search(query: SearchQuery, datasets: List<String>? = null): SearchResult

Parameters

Name	Type	Description
query	SearchQuery	The text and index fields to match, on the device.
scope	{ datasets?: string[] }, optional	Restricts the search to the datasets named. Otherwise searches every dataset in the person’s data scope.

Returns: SearchResult: the matching entries, and which indexes were denied.

Records: Query Records, one per index opened.

Errors: locked, no-session, unreachable.

Types

VersionInfo

TypeScript

interface VersionInfo {
  version: number;
  savedAt: Date;
  writer: RecipientId;
  baseVersion?: number;
  pending: boolean;
  retired: boolean;
}

Swift

struct VersionInfo {
  let version: Int
  let savedAt: Date
  let writer: RecipientId
  let baseVersion: Int?
  let pending: Bool
  let retired: Bool
}

Kotlin

data class VersionInfo(
  val version: Int,
  val savedAt: Instant,
  val writer: RecipientId,
  val baseVersion: Int? = null,
  val pending: Boolean,
  val retired: Boolean,
)

Field	Type	Description
version	number	The version number.
savedAt	Date	When this version was saved.
writer	RecipientId	The device that saved it.
baseVersion	number, optional	The version it was saved from.
pending	boolean	An AI agent’s version, written but not current until its delegator accepts it.
retired	boolean	Whether this version is in the recycle bin.

Entry

TypeScript

interface Entry {
  locator: Locator;
  kind: ObjectKind | 'folder';
  name: string;
  type?: string;
  times: { created: Date; saved: Date };
  currentVersion?: number;
  versions: VersionInfo[];
  indexFields: { [field: string]: FieldValue };
  recipients: Person[];
  domainRoot?: Locator;
}

Swift

struct Entry {
  let locator: Locator
  let kind: Entry.Kind
  let name: String
  let type: String?
  let times: (created: Date, saved: Date)
  let currentVersion: Int?
  let versions: [VersionInfo]
  let indexFields: [String: FieldValue]
  let recipients: [Person]
  let domainRoot: Locator?
}

Kotlin

data class Entry(
  val locator: Locator,
  val kind: EntryKind,
  val name: String,
  val type: String? = null,
  val times: Times,
  val currentVersion: Int? = null,
  val versions: List<VersionInfo>,
  val indexFields: Map<String, FieldValue>,
  val recipients: List<Person>,
  val domainRoot: Locator? = null,
)

Field	Type	Description
locator	Locator	The entry’s locator.
kind	ObjectKind | 'folder'	Whether this entry is a record, a file, or a folder.
name	string	Only a device that may open the index sees a name.
type	string, optional	The media type, for a file.
times	{ created, saved }	When the entry was created and last saved.
currentVersion	number, optional	The current version, absent for a folder.
versions	VersionInfo[]	Every version of this entry.
indexFields	{ [field: string]: FieldValue }	The dataset’s index fields as the Client that saved the version wrote them.
recipients	Person[]	The record’s recipients. The next save keeps their access too.
domainRoot	Locator, optional	For a folder that is a key domain of its own.

Listing

TypeScript

interface Listing {
  dataset: string;
  domain: Locator;
  folder: Locator;
  entries: Entry[];
}

Swift

struct Listing {
  let dataset: String
  let domain: Locator
  let folder: Locator
  let entries: [Entry]
}

Kotlin

data class Listing(
  val dataset: String,
  val domain: Locator,
  val folder: Locator,
  val entries: List<Entry>,
)

Field	Type	Description
dataset	string	The dataset the folder belongs to.
domain	Locator	The key domain the folder’s index is under.
folder	Locator	The folder that was listed.
entries	Entry[]	The folder’s entries.

SearchQuery

TypeScript

interface SearchQuery {
  text?: string;
  indexFields?: { [field: string]: FieldValue };
  kind?: ObjectKind;
  savedFrom?: Date;
  savedTo?: Date;
}

Swift

struct SearchQuery {
  var text: String? = nil
  var indexFields: [String: FieldValue]? = nil
  var kind: ObjectKind? = nil
  var savedFrom: Date? = nil
  var savedTo: Date? = nil
}

Kotlin

data class SearchQuery(
  val text: String? = null,
  val indexFields: Map<String, FieldValue>? = null,
  val kind: ObjectKind? = null,
  val savedFrom: Instant? = null,
  val savedTo: Instant? = null,
)

Field	Type	Description
text	string, optional	Matched over names and index fields, on the device.
indexFields	{ [field: string]: FieldValue }, optional	Exact index field values to match.
kind	ObjectKind, optional	Restricts to records or files.
savedFrom	Date, optional	Only entries saved on or after this date.
savedTo	Date, optional	Only entries saved on or before this date.

SearchResult

TypeScript

interface SearchResult {
  entries: (Entry & { dataset: string; domain: Locator; folder: Locator })[];
  indexes: { domain: Locator; decision: Decided<{}> }[];
}

Swift

struct SearchResult {
  let entries: [SearchResult.FoundEntry]
  let indexes: [(domain: Locator, decision: Decided<Void>)]
}

Kotlin

data class SearchResult(
  val entries: List<FoundEntry>,
  val indexes: List<IndexDecision>,
)

Field	Type	Description
entries	an Entry, plus dataset, domain and folder	The matching entries, with where each one lives.
indexes	{ domain, decision }[]	One decision per folder index opened. A denied index yields no entries and is listed here.

Folders

TypeScript

interface Folders {
  list(folder: Locator): Promise<Decided<Listing>>;
  search(query: SearchQuery, scope?: { datasets?: string[] }): Promise<SearchResult>;
}

Swift

class Folders {
  func list(_ folder: Locator) async throws -> Decided<Listing>
  func search(_ query: SearchQuery, datasets: [String]? = nil) async throws -> SearchResult
}

Kotlin

class Folders {
  suspend fun list(folder: Locator): Decided<Listing>
  suspend fun search(query: SearchQuery, datasets: List<String>? = null): SearchResult
}

Folders groups the two methods above into the namespace client.folders.