@enbox/api 0.1.1 → 0.2.1

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.1",
+  "version": "0.2.1",
   "description": "SDK for accessing the features and capabilities of Web5",
   "type": "module",
   "main": "./dist/esm/index.js",
@@ -16,7 +16,7 @@
     "test:node": "bun test --timeout 10000 .spec.ts",
     "test:node:coverage": "bun test --timeout 10000 --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage .spec.ts",
     "test:browser": "bunx --bun vitest --config vitest.browser.config.ts --run",
-    "test:browser:coverage": "bunx --bun vitest --config vitest.browser.config.ts --run --coverage --coverage.provider=istanbul --coverage.reportsDirectory=./coverage-browser"
+    "test:browser:coverage": "bunx --bun vitest --config vitest.browser.config.ts --run --coverage --coverage.provider=istanbul"
   },
   "homepage": "https://github.com/enboxorg/enbox/tree/main/packages/api#readme",
   "bugs": "https://github.com/enboxorg/enbox/issues",
@@ -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.5",
+    "@enbox/agent": "0.1.7",
     "@enbox/common": "0.0.3",
-    "@enbox/dwn-clients": "0.0.3"
+    "@enbox/dwn-clients": "0.0.4"
   },
   "devDependencies": {
     "@enbox/crypto": "0.0.4",
-    "@enbox/dids": "0.0.4",
-    "@enbox/dwn-sdk-js": "0.0.6",
+    "@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.
  * ```
  */