@enbox/api 0.1.0 → 0.2.0

package/dist/types/{typed-dwn-api.d.ts → typed-web5.d.ts}

@@ -1,23 +1,43 @@
 /**
- * A type-safe wrapper around {@link DwnApi} scoped to a single protocol.
+ * A protocol-scoped API returned by {@link Web5.using}.
  *
- * `TypedDwnApi` is created via `dwn.using(typedProtocol)` and provides
- * autocompletion for protocol paths, typed data payloads, and tag shapes.
+ * `TypedWeb5` is the **primary developer interface** for interacting with
+ * protocol-backed records. It auto-injects the protocol URI, protocolPath,
+ * and schema into every operation, and provides compile-time path
+ * autocompletion plus typed data payloads via the schema map.
  *
- * Every method delegates to the corresponding `dwn.records.*` method,
- * injecting the protocol URI, protocolPath, and schema automatically.
+ * @example
+ * ```ts
+ * const social = web5.using(SocialProtocol);
+ *
+ * // Install the protocol
+ * await social.configure();
+ *
+ * // Write — path and data type are checked at compile time
+ * const { record } = await social.records.write('thread', {
+ *   data: { title: 'Hello World', body: '...' },
+ * });
+ *
+ * // Query — protocol and protocolPath are auto-injected
+ * const { records } = await social.records.query('thread');
+ *
+ * // Subscribe — real-time changes via LiveQuery
+ * const { liveQuery } = await social.records.subscribe('thread/reply');
+ * liveQuery.on('create', (record) => { ... });
+ * ```
  */
+import type { DwnApi } from './dwn-api.js';
+import type { LiveQuery } from './live-query.js';
 import type { Protocol } from './protocol.js';
 import type { Record } from './record.js';
 import type { DateSort, ProtocolDefinition, ProtocolType, RecordsFilter } from '@enbox/dwn-sdk-js';
-import type { DwnApi, RecordsSubscriptionHandler } from './dwn-api.js';
-import type { DwnMessageSubscription, DwnPaginationCursor, DwnResponseStatus } from '@enbox/agent';
+import type { DwnPaginationCursor, DwnResponseStatus } from '@enbox/agent';
 import type { ProtocolPaths, SchemaMap, TypedProtocol, TypeNameAtPath } from './protocol-types.js';
 /**
  * Resolves the TypeScript data type for a given protocol path.
  *
  * If the schema map contains a mapping for the type name at the given path,
- * that type is returned.  Otherwise falls back to `unknown`.
+ * that type is returned. Otherwise falls back to `unknown`.
  */
 type DataForPath<_D extends ProtocolDefinition, M extends SchemaMap, Path extends string> = TypeNameAtPath<Path> extends keyof M ? M[TypeNameAtPath<Path>] : unknown;
 /**
@@ -30,34 +50,31 @@ type ProtocolTypeForPath<D extends ProtocolDefinition, Path extends string> = Ty
 type DataFormatForPath<D extends ProtocolDefinition, Path extends string> = ProtocolTypeForPath<D, Path> extends {
     dataFormats: infer F;
 } ? F extends readonly string[] ? F[number] : string : string;
-/** Options for `TypedDwnApi.write()`. */
+/** Options for {@link TypedWeb5} `records.write()`. */
 export type TypedWriteRequest<D extends ProtocolDefinition, M extends SchemaMap, Path extends string> = {
     /** The data payload. Type-checked against the schema map. */
     data: DataForPath<D, M, Path>;
-    /** Additional message parameters (protocolPath and protocol are injected). */
-    message?: {
-        parentContextId?: string;
-        published?: boolean;
-        datePublished?: string;
-        recipient?: string;
-        protocolRole?: string;
-        dataFormat?: DataFormatForPath<D, Path>;
-        tags?: globalThis.Record<string, string | number | boolean | string[] | number[]>;
-    };
+    parentContextId?: string;
+    published?: boolean;
+    datePublished?: string;
+    recipient?: string;
+    protocolRole?: string;
+    dataFormat?: DataFormatForPath<D, Path>;
+    tags?: globalThis.Record<string, string | number | boolean | string[] | number[]>;
     /** Whether to persist immediately (defaults to `true`). */
     store?: boolean;
     /** Whether to auto-encrypt (follows protocol definition if omitted). */
     encryption?: boolean;
 };
-/** Response from `TypedDwnApi.write()`. */
+/** Response from {@link TypedWeb5} `records.write()`. */
 export type TypedWriteResponse = DwnResponseStatus & {
-    record?: Record;
+    record: Record;
 };
-/** Filter options for `TypedDwnApi.query()`. */
+/** Filter options for {@link TypedWeb5} `records.query()`. */
 export type TypedQueryFilter = Omit<RecordsFilter, 'protocol' | 'protocolPath' | 'schema'> & {
     tags?: globalThis.Record<string, string | number | boolean | (string | number)[]>;
 };
-/** Options for `TypedDwnApi.query()`. */
+/** Options for {@link TypedWeb5} `records.query()`. */
 export type TypedQueryRequest = {
     /** Optional remote DWN DID to query from. */
     from?: string;
@@ -72,12 +89,12 @@ export type TypedQueryRequest = {
     /** When true, automatically decrypts encrypted records. */
     encryption?: boolean;
 };
-/** Response from `TypedDwnApi.query()`. */
+/** Response from {@link TypedWeb5} `records.query()`. */
 export type TypedQueryResponse = DwnResponseStatus & {
-    records?: Record[];
+    records: Record[];
     cursor?: DwnPaginationCursor;
 };
-/** Options for `TypedDwnApi.read()`. */
+/** Options for {@link TypedWeb5} `records.read()`. */
 export type TypedReadRequest = {
     /** Optional remote DWN DID to read from. */
     from?: string;
@@ -86,54 +103,52 @@ export type TypedReadRequest = {
     /** When true, automatically decrypts the record. */
     encryption?: boolean;
 };
-/** Response from `TypedDwnApi.read()`. */
+/** Response from {@link TypedWeb5} `records.read()`. */
 export type TypedReadResponse = DwnResponseStatus & {
     record: Record;
 };
-/** Options for `TypedDwnApi.delete()`. */
+/** Options for {@link TypedWeb5} `records.delete()`. */
 export type TypedDeleteRequest = {
     /** Optional remote DWN DID to delete from. */
     from?: string;
     /** The `recordId` of the record to delete. */
     recordId: string;
 };
-/** Options for `TypedDwnApi.subscribe()`. */
+/** Options for {@link TypedWeb5} `records.subscribe()`. */
 export type TypedSubscribeRequest = {
     /** Optional remote DWN DID to subscribe to. */
     from?: string;
     /** Subscription filter (protocol, protocolPath, schema are injected). */
     filter?: TypedQueryFilter;
     protocolRole?: string;
-    subscriptionHandler: RecordsSubscriptionHandler;
-    /** When true, indicates encryption is active. */
-    encryption?: boolean;
 };
-/** Response from `TypedDwnApi.subscribe()`. */
+/** Response from {@link TypedWeb5} `records.subscribe()`. */
 export type TypedSubscribeResponse = DwnResponseStatus & {
-    subscription?: DwnMessageSubscription;
+    /** The live query instance, or `undefined` if the request failed. */
+    liveQuery?: LiveQuery;
 };
 /**
- * A protocol-scoped wrapper around `DwnApi` that automatically injects
- * the `protocol` URI, `protocolPath`, and `schema` into every DWN operation.
+ * A protocol-scoped API that auto-injects `protocol`, `protocolPath`, and
+ * `schema` into every DWN operation.
  *
- * Obtain an instance via `dwn.using(typedProtocol)`.
+ * Obtain an instance via `web5.using(typedProtocol)`.
  *
  * @example
  * ```ts
- * const social = dwn.using(SocialGraphProtocol);
+ * const social = web5.using(SocialProtocol);
  *
- * // Write — path and data type are checked at compile time
- * const { record } = await social.write('friend', {
+ * await social.configure();
+ *
+ * const { record } = await social.records.write('friend', {
  *   data: { did: 'did:example:alice', alias: 'Alice' },
  * });
  *
- * // Query — protocol and protocolPath are auto-injected
- * const { records } = await social.query('friend', {
+ * const { records } = await social.records.query('friend', {
  *   filter: { tags: { did: 'did:example:alice' } },
  * });
  * ```
  */
-export declare class TypedDwnApi<D extends ProtocolDefinition = ProtocolDefinition, M extends SchemaMap = SchemaMap> {
+export declare class TypedWeb5<D extends ProtocolDefinition = ProtocolDefinition, M extends SchemaMap = SchemaMap> {
     private _dwn;
     private _definition;
     constructor(dwn: DwnApi, protocol: TypedProtocol<D, M>);
@@ -144,6 +159,11 @@ export declare class TypedDwnApi<D extends ProtocolDefinition = ProtocolDefiniti
     /**
      * Configures (installs) this protocol on the local DWN.
      *
+     * If the protocol is already installed with an identical definition,
+     * this is a no-op and returns the existing protocol. If the definition
+     * has changed (e.g. new types, modified structure), the protocol is
+     * re-configured with the updated definition.
+     *
      * @param options - Optional overrides like `encryption`.
      */
     configure(options?: {
@@ -152,40 +172,19 @@ export declare class TypedDwnApi<D extends ProtocolDefinition = ProtocolDefiniti
         protocol?: Protocol;
     }>;
     /**
-     * Write a record at the given protocol path.
-     *
-     * @param path - The protocol path (e.g. `'friend'`, `'group/member'`).
-     * @param request - Write options including typed `data`.
-     */
-    write<Path extends ProtocolPaths<D> & string>(path: Path, request: TypedWriteRequest<D, M, Path>): Promise<TypedWriteResponse>;
-    /**
-     * Query records at the given protocol path.
-     *
-     * @param path - The protocol path to query.
-     * @param request - Query options including optional filter, sort, and pagination.
-     */
-    query<Path extends ProtocolPaths<D> & string>(path: Path, request?: TypedQueryRequest): Promise<TypedQueryResponse>;
-    /**
-     * Read a single record at the given protocol path.
+     * Protocol-scoped record operations.
      *
-     * @param path - The protocol path to read from.
-     * @param request - Read options including a filter to identify the record.
+     * Every method auto-injects the protocol URI, protocolPath, and schema
+     * from the protocol definition. Path parameters provide compile-time
+     * autocompletion via `ProtocolPaths<D>`.
      */
-    read<Path extends ProtocolPaths<D> & string>(path: Path, request: TypedReadRequest): Promise<TypedReadResponse>;
-    /**
-     * Delete a record at the given protocol path.
-     *
-     * @param path - The protocol path (used for permission scoping).
-     * @param request - Delete options including the `recordId`.
-     */
-    delete<Path extends ProtocolPaths<D> & string>(_path: Path, request: TypedDeleteRequest): Promise<DwnResponseStatus>;
-    /**
-     * Subscribe to records at the given protocol path.
-     *
-     * @param path - The protocol path to subscribe to.
-     * @param request - Subscribe options including the subscription handler.
-     */
-    subscribe<Path extends ProtocolPaths<D> & string>(path: Path, request: TypedSubscribeRequest): Promise<TypedSubscribeResponse>;
+    get records(): {
+        write: <Path extends ProtocolPaths<D> & string>(path: Path, request: TypedWriteRequest<D, M, Path>) => Promise<TypedWriteResponse>;
+        query: <Path extends ProtocolPaths<D> & string>(path: Path, request?: TypedQueryRequest) => Promise<TypedQueryResponse>;
+        read: <Path extends ProtocolPaths<D> & string>(path: Path, request: TypedReadRequest) => Promise<TypedReadResponse>;
+        delete: <Path extends ProtocolPaths<D> & string>(path: Path, request: TypedDeleteRequest) => Promise<DwnResponseStatus>;
+        subscribe: <Path extends ProtocolPaths<D> & string>(path: Path, request?: TypedSubscribeRequest) => Promise<TypedSubscribeResponse>;
+    };
 }
 export {};
-//# sourceMappingURL=typed-dwn-api.d.ts.map
+//# sourceMappingURL=typed-web5.d.ts.map

package/dist/types/typed-web5.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-web5.d.ts","sourceRoot":"","sources":["../../src/typed-web5.ts"],"names":[],"mappings":"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"}

package/dist/types/web5.d.ts

@@ -2,9 +2,13 @@
  * NOTE: Added reference types here to avoid a `pnpm` bug during build.
  * https://github.com/enboxorg/enbox/pull/507
  */
+import type { DidMethodResolver } from '@enbox/dids';
+import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
 import type { DwnDataEncodedRecordsWriteMessage, DwnProtocolDefinition, HdIdentityVault, Permission, WalletConnectOptions, Web5Agent } from '@enbox/agent';
+import type { SchemaMap, TypedProtocol } from './protocol-types.js';
 import { DidApi } from './did-api.js';
-import { DwnApi } from './dwn-api.js';
+import { DwnReaderApi } from './dwn-reader-api.js';
+import { TypedWeb5 } from './typed-web5.js';
 import { VcApi } from './vc-api.js';
 /** Override defaults configured during the technical preview phase. */
 export type TechPreviewOptions = {
@@ -43,6 +47,26 @@ export type ConnectOptions = Omit<WalletConnectOptions, 'permissionRequests'> &
      */
     permissionRequests: ConnectPermissionRequest[];
 };
+/**
+ * Options for creating an anonymous (read-only) Web5 instance via {@link Web5.anonymous}.
+ *
+ * @beta
+ */
+export type Web5AnonymousOptions = {
+    /** Override the default DID method resolvers. Defaults to `[DidDht, DidJwk, DidKey, DidWeb]`. */
+    didResolvers?: DidMethodResolver[];
+};
+/**
+ * The result of calling {@link Web5.anonymous}.
+ *
+ * Contains only a read-only `dwn` property — no `did`, `vc`, or `agent`.
+ *
+ * @beta
+ */
+export type Web5AnonymousApi = {
+    /** A read-only DWN API for querying public data on remote DWNs. */
+    dwn: DwnReaderApi;
+};
 /** Optional overrides that can be provided when calling {@link Web5.connect}. */
 export type Web5ConnectOptions = {
     /**
@@ -184,11 +208,63 @@ export declare class Web5 {
     agent: Web5Agent;
     /** Exposed instance to the DID APIs, allow users to create and resolve DIDs  */
     did: DidApi;
-    /** Exposed instance to the DWN APIs, allow users to read/write records */
-    dwn: DwnApi;
+    /** Internal DWN API instance. Use {@link Web5.using} for protocol-scoped access. */
+    private _dwn;
     /** Exposed instance to the VC APIs, allow users to issue, present and verify VCs */
     vc: VcApi;
     constructor({ agent, connectedDid, delegateDid }: Web5Params);
+    /**
+     * Returns a {@link TypedWeb5} instance scoped to the given protocol.
+     *
+     * This is the **primary developer interface** for interacting with
+     * protocol-backed records. It auto-injects the protocol URI, protocolPath,
+     * and schema into every operation, and provides compile-time path
+     * autocompletion plus typed data payloads via the schema map.
+     *
+     * @param protocol - A typed protocol created via `defineProtocol()`.
+     * @returns A `TypedWeb5` instance bound to the given protocol.
+     *
+     * @example
+     * ```ts
+     * const social = web5.using(SocialProtocol);
+     *
+     * await social.configure();
+     *
+     * const { record } = await social.records.write('friend', {
+     *   data: { did: 'did:example:alice', alias: 'Alice' },
+     * });
+     *
+     * const { records } = await social.records.query('friend');
+     * ```
+     */
+    using<D extends ProtocolDefinition, M extends SchemaMap>(protocol: TypedProtocol<D, M>): TypedWeb5<D, M>;
+    /**
+     * Creates a lightweight, read-only Web5 instance for querying public DWN data.
+     *
+     * No identity, vault, password, or signing keys are required. The returned
+     * API supports querying and reading published records and protocols from any
+     * remote DWN, using **unsigned** (anonymous) DWN messages.
+     *
+     * @param options - Optional configuration overrides.
+     * @returns A {@link Web5AnonymousApi} with a read-only `dwn` property.
+     *
+     * @example
+     * ```ts
+     * const { dwn } = Web5.anonymous();
+     *
+     * const { records } = await dwn.records.query({
+     *   from: 'did:dht:alice...',
+     *   filter: { protocol: 'https://social.example/posts', protocolPath: 'post' },
+     * });
+     *
+     * for (const record of records) {
+     *   console.log(record.id, await record.data.text());
+     * }
+     * ```
+     *
+     * @beta
+     */
+    static anonymous(options?: Web5AnonymousOptions): Web5AnonymousApi;
     /**
      * Connects to a {@link Web5Agent}. Defaults to creating a local {@link Web5UserAgent} if one
      * isn't provided.

package/dist/types/web5.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web5.d.ts","sourceRoot":"","sources":["../../src/web5.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"web5.d.ts","sourceRoot":"","sources":["../../src/web5.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/api",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SDK for accessing the features and capabilities of Web5",
   "type": "module",
   "main": "./dist/esm/index.js",
@@ -53,6 +53,10 @@
       "types": "./dist/types/index.d.ts",
       "import": "./dist/esm/index.js"
     },
+    "./advanced": {
+      "types": "./dist/types/advanced.d.ts",
+      "import": "./dist/esm/advanced.js"
+    },
     "./browser": {
       "types": "./dist/types/index.d.ts",
       "import": "./dist/browser.mjs"
@@ -77,14 +81,14 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
-    "@enbox/agent": "0.1.4",
+    "@enbox/agent": "0.1.6",
     "@enbox/common": "0.0.3",
-    "@enbox/dwn-clients": "0.0.2"
+    "@enbox/dwn-clients": "0.0.4"
   },
   "devDependencies": {
-    "@enbox/crypto": "0.0.3",
-    "@enbox/dids": "0.0.3",
-    "@enbox/dwn-sdk-js": "0.0.5",
+    "@enbox/crypto": "0.0.4",
+    "@enbox/dids": "0.0.5",
+    "@enbox/dwn-sdk-js": "0.0.7",
     "@types/node": "20.14.8",
     "@types/sinon": "17.0.3",
     "@typescript-eslint/eslint-plugin": "8.32.1",

package/src/advanced.ts

@@ -0,0 +1,29 @@
+/**
+ * Advanced API surface for power users who need direct access to
+ * the underlying {@link DwnApi}.
+ *
+ * Most applications should use `web5.using(protocol)` instead.
+ * Import from `@enbox/api/advanced` to access these exports.
+ *
+ * @packageDocumentation
+ */
+
+export { DwnApi } from './dwn-api.js';
+
+export type {
+  FetchGrantsRequest,
+  FetchRequestsRequest,
+  ProtocolsConfigureRequest,
+  ProtocolsConfigureResponse,
+  ProtocolsQueryRequest,
+  ProtocolsQueryResponse,
+  RecordsDeleteRequest,
+  RecordsQueryRequest,
+  RecordsQueryResponse,
+  RecordsReadRequest,
+  RecordsReadResponse,
+  RecordsSubscribeRequest,
+  RecordsSubscribeResponse,
+  RecordsWriteRequest,
+  RecordsWriteResponse,
+} from './dwn-api.js';

package/src/define-protocol.ts

@@ -2,7 +2,7 @@
  * Factory function for creating typed protocol definitions.
  *
  * `defineProtocol()` wraps a standard {@link ProtocolDefinition} with
- * compile-time type metadata so that {@link TypedDwnApi} can provide
+ * compile-time type metadata so that {@link TypedWeb5} can provide
  * path autocompletion, data-shape inference, and tag type safety.
  */
 
@@ -17,7 +17,7 @@ import type { SchemaMap, TypedProtocol } from './protocol-types.js';
  *
  * The `definition` argument is returned as-is (no cloning). The schema map
  * is a phantom type parameter — it exists only at compile time to thread
- * type information through to `TypedDwnApi`.
+ * type information through to `TypedWeb5`.
  *
  * @param definition - A standard `ProtocolDefinition` object.
  * @param _schemaMap - A phantom value (e.g. `{} as MySchemaMap`) that carries
@@ -32,7 +32,7 @@ import type { SchemaMap, TypedProtocol } from './protocol-types.js';
  * });
  *
  * // socialGraph.definition is the raw ProtocolDefinition
- * // TypedDwnApi infers paths like 'friend' | 'friend/message' and
+ * // TypedWeb5 infers paths like 'friend' | 'friend/message' and
  * // data types from the schema map.
  * ```
  */