@enbox/api 0.0.8 → 0.1.0

package/src/protocol-types.ts

@@ -0,0 +1,171 @@
+/**
+ * Type-level utilities for extracting typed paths, type names, schemas,
+ * data formats, and tag shapes from a {@link ProtocolDefinition}.
+ *
+ * These types are purely compile-time — they produce no runtime code.
+ */
+
+import type { ProtocolDefinition, ProtocolRuleSet, ProtocolTagsDefinition, ProtocolType } from '@enbox/dwn-sdk-js';
+
+// ---------------------------------------------------------------------------
+// Path extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively extracts all valid protocol path strings from a `ProtocolRuleSet`.
+ *
+ * Given a structure like `{ foo: { bar: { ... } } }`, this produces
+ * `'foo' | 'foo/bar'`.  Directive keys (starting with `$`) are excluded.
+ */
+export type RuleSetPaths<R, Prefix extends string = ''> = {
+  [K in Extract<keyof R, string>]: K extends `$${string}`
+    ? never
+    : R[K] extends ProtocolRuleSet
+      ? `${Prefix}${K}` | RuleSetPaths<R[K], `${Prefix}${K}/`>
+      : never;
+}[Extract<keyof R, string>];
+
+/**
+ * All valid protocol path strings for a given `ProtocolDefinition`.
+ *
+ * @example
+ * ```ts
+ * type Paths = ProtocolPaths<typeof myDef>;
+ * // 'friend' | 'friend/message' | 'group' | 'group/member'
+ * ```
+ */
+export type ProtocolPaths<D extends ProtocolDefinition> = RuleSetPaths<D['structure']>;
+
+// ---------------------------------------------------------------------------
+// Type-name extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extracts the last segment (type name) from a protocol path string.
+ *
+ * @example
+ * ```ts
+ * type T = TypeNameAtPath<'group/member'>; // 'member'
+ * ```
+ */
+export type TypeNameAtPath<Path extends string> =
+  Path extends `${string}/${infer Rest}`
+    ? TypeNameAtPath<Rest>
+    : Path;
+
+// ---------------------------------------------------------------------------
+// Schema & data-format lookup
+// ---------------------------------------------------------------------------
+
+/**
+ * The type names declared in the `types` map of a `ProtocolDefinition`.
+ */
+export type TypeNames<D extends ProtocolDefinition> = Extract<keyof D['types'], string>;
+
+/**
+ * Looks up the `schema` URI for a given type name in the protocol definition.
+ * Returns `undefined` if the type does not declare a schema.
+ */
+export type SchemaForType<D extends ProtocolDefinition, TypeName extends string> =
+  TypeName extends keyof D['types']
+    ? D['types'][TypeName] extends ProtocolType
+      ? D['types'][TypeName]['schema']
+      : undefined
+    : undefined;
+
+/**
+ * Looks up the `dataFormats` array for a given type name in the protocol definition.
+ * Returns `undefined` if the type does not declare dataFormats.
+ */
+export type DataFormatsForType<D extends ProtocolDefinition, TypeName extends string> =
+  TypeName extends keyof D['types']
+    ? D['types'][TypeName] extends ProtocolType
+      ? D['types'][TypeName]['dataFormats']
+      : undefined
+    : undefined;
+
+// ---------------------------------------------------------------------------
+// Tag extraction helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Navigates a `ProtocolRuleSet` tree to the node at the given slash-delimited path.
+ */
+type RuleSetAtPath<R, Path extends string> =
+  Path extends `${infer Head}/${infer Tail}`
+    ? Head extends keyof R
+      ? R[Head] extends ProtocolRuleSet
+        ? RuleSetAtPath<R[Head], Tail>
+        : never
+      : never
+    : Path extends keyof R
+      ? R[Path] extends ProtocolRuleSet
+        ? R[Path]
+        : never
+      : never;
+
+/**
+ * Extracts the `$tags` definition for a given protocol path.
+ * Returns `never` if the path does not declare `$tags`.
+ */
+export type TagsAtPath<D extends ProtocolDefinition, Path extends string> =
+  RuleSetAtPath<D['structure'], Path> extends infer RS
+    ? RS extends ProtocolRuleSet
+      ? RS['$tags'] extends ProtocolTagsDefinition
+        ? RS['$tags']
+        : never
+      : never
+    : never;
+
+/**
+ * Extracts the user-defined tag keys (excluding `$`-prefixed meta-keys)
+ * from a `ProtocolTagsDefinition`.
+ */
+export type TagKeys<Tags extends ProtocolTagsDefinition> = Exclude<
+  Extract<keyof Tags, string>,
+  `$${string}`
+>;
+
+// ---------------------------------------------------------------------------
+// Schema map — associates TypeScript data types with protocol type names
+// ---------------------------------------------------------------------------
+
+/**
+ * A mapping from protocol type names to their TypeScript data shapes.
+ *
+ * Used as a type parameter to `defineProtocol()` and `TypedDwnApi` so that
+ * the protocol definition JSON stays JSON-compatible while TypeScript types
+ * are tracked separately.
+ *
+ * @example
+ * ```ts
+ * type MySchemaMap = {
+ *   profile : { displayName: string; bio?: string };
+ *   avatar  : Blob;
+ * };
+ * ```
+ */
+export type SchemaMap = Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// Typed protocol — output of defineProtocol()
+// ---------------------------------------------------------------------------
+
+/**
+ * The return type of `defineProtocol()`. Bundles the raw protocol definition
+ * with its inferred path strings and schema type map for downstream use
+ * by `TypedDwnApi`.
+ */
+export type TypedProtocol<
+  D extends ProtocolDefinition = ProtocolDefinition,
+  M extends SchemaMap = SchemaMap,
+> = {
+  /** The raw DWN protocol definition (JSON-compatible). */
+  readonly definition: D;
+
+  /**
+   * Phantom property carrying the schema map type. Not present at runtime;
+   * used only by TypeScript to thread the generic through.
+   */
+  readonly _schemaMap?: M;
+};

package/src/record.ts

@@ -445,7 +445,7 @@ export class Record implements RecordModel {
   get data(): {
       blob: () => Promise<Blob>;
       bytes: () => Promise<Uint8Array>;
-      json: () => Promise<any>;
+      json: <T = unknown>() => Promise<T>;
       text: () => Promise<string>;
       stream: () => Promise<ReadableStream>;
       then: (
@@ -489,8 +489,8 @@ export class Record implements RecordModel {
        *
        * @beta
        */
-      async json(): Promise<any> {
-        return await Stream.consumeToJson({ readableStream: await this.stream() });
+      async json<T = unknown>(): Promise<T> {
+        return await Stream.consumeToJson({ readableStream: await this.stream() }) as T;
       },
 
       /**

package/src/typed-dwn-api.ts

@@ -0,0 +1,370 @@
+/**
+ * A type-safe wrapper around {@link DwnApi} scoped to a single protocol.
+ *
+ * `TypedDwnApi` is created via `dwn.using(typedProtocol)` and provides
+ * autocompletion for protocol paths, typed data payloads, and tag shapes.
+ *
+ * Every method delegates to the corresponding `dwn.records.*` method,
+ * injecting the protocol URI, protocolPath, and schema automatically.
+ */
+
+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 { ProtocolPaths, SchemaMap, TypedProtocol, TypeNameAtPath } from './protocol-types.js';
+
+// ---------------------------------------------------------------------------
+// Helper types
+// ---------------------------------------------------------------------------
+
+/**
+ * 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`.
+ */
+type DataForPath<
+  _D extends ProtocolDefinition,
+  M extends SchemaMap,
+  Path extends string,
+> = TypeNameAtPath<Path> extends keyof M ? M[TypeNameAtPath<Path>] : unknown;
+
+/**
+ * Resolves the `ProtocolType` entry for a given protocol path.
+ */
+type ProtocolTypeForPath<
+  D extends ProtocolDefinition,
+  Path extends string,
+> = TypeNameAtPath<Path> extends keyof D['types']
+  ? D['types'][TypeNameAtPath<Path>] extends ProtocolType
+    ? D['types'][TypeNameAtPath<Path>]
+    : undefined
+  : undefined;
+
+/**
+ * Resolves a `dataFormat` string literal union for a path, or `string` if none.
+ */
+type DataFormatForPath<
+  D extends ProtocolDefinition,
+  Path extends string,
+> = ProtocolTypeForPath<D, Path> extends { dataFormats: infer F }
+  ? F extends readonly string[]
+    ? F[number]
+    : string
+  : string;
+
+// ---------------------------------------------------------------------------
+// Request / response types
+// ---------------------------------------------------------------------------
+
+/** Options for `TypedDwnApi.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[]>;
+  };
+
+  /** Whether to persist immediately (defaults to `true`). */
+  store?: boolean;
+
+  /** Whether to auto-encrypt (follows protocol definition if omitted). */
+  encryption?: boolean;
+};
+
+/** Response from `TypedDwnApi.write()`. */
+export type TypedWriteResponse = DwnResponseStatus & {
+  record?: Record;
+};
+
+/** Filter options for `TypedDwnApi.query()`. */
+export type TypedQueryFilter = Omit<RecordsFilter, 'protocol' | 'protocolPath' | 'schema'> & {
+  tags?: globalThis.Record<string, string | number | boolean | (string | number)[]>;
+};
+
+/** Options for `TypedDwnApi.query()`. */
+export type TypedQueryRequest = {
+  /** Optional remote DWN DID to query from. */
+  from?: string;
+
+  /** Query filter (protocol, protocolPath, schema are injected). */
+  filter? : TypedQueryFilter;
+  dateSort? : DateSort;
+  pagination? : { limit?: number; cursor?: DwnPaginationCursor };
+  protocolRole? : string;
+
+  /** When true, automatically decrypts encrypted records. */
+  encryption?: boolean;
+};
+
+/** Response from `TypedDwnApi.query()`. */
+export type TypedQueryResponse = DwnResponseStatus & {
+  records?: Record[];
+  cursor? : DwnPaginationCursor;
+};
+
+/** Options for `TypedDwnApi.read()`. */
+export type TypedReadRequest = {
+  /** Optional remote DWN DID to read from. */
+  from?: string;
+
+  /** Filter to identify the record (protocol and protocolPath are injected). */
+  filter: Omit<RecordsFilter, 'protocol' | 'protocolPath' | 'schema'>;
+
+  /** When true, automatically decrypts the record. */
+  encryption?: boolean;
+};
+
+/** Response from `TypedDwnApi.read()`. */
+export type TypedReadResponse = DwnResponseStatus & {
+  record: Record;
+};
+
+/** Options for `TypedDwnApi.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()`. */
+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()`. */
+export type TypedSubscribeResponse = DwnResponseStatus & {
+  subscription?: DwnMessageSubscription;
+};
+
+// ---------------------------------------------------------------------------
+// TypedDwnApi class
+// ---------------------------------------------------------------------------
+
+/**
+ * A protocol-scoped wrapper around `DwnApi` that automatically injects
+ * the `protocol` URI, `protocolPath`, and `schema` into every DWN operation.
+ *
+ * Obtain an instance via `dwn.using(typedProtocol)`.
+ *
+ * @example
+ * ```ts
+ * const social = dwn.using(SocialGraphProtocol);
+ *
+ * // Write — path and data type are checked at compile time
+ * const { record } = await social.write('friend', {
+ *   data: { did: 'did:example:alice', alias: 'Alice' },
+ * });
+ *
+ * // Query — protocol and protocolPath are auto-injected
+ * const { records } = await social.query('friend', {
+ *   filter: { tags: { did: 'did:example:alice' } },
+ * });
+ * ```
+ */
+export class TypedDwnApi<
+  D extends ProtocolDefinition = ProtocolDefinition,
+  M extends SchemaMap = SchemaMap,
+> {
+  private _dwn: DwnApi;
+  private _definition: D;
+
+  constructor(dwn: DwnApi, protocol: TypedProtocol<D, M>) {
+    this._dwn = dwn;
+    this._definition = protocol.definition;
+  }
+
+  /** The protocol URI. */
+  public get protocol(): string {
+    return this._definition.protocol;
+  }
+
+  /** The raw protocol definition. */
+  public get definition(): D {
+    return this._definition;
+  }
+
+  /**
+   * Configures (installs) this protocol on the local DWN.
+   *
+   * @param options - Optional overrides like `encryption`.
+   */
+  public async configure(options?: { encryption?: boolean }): Promise<DwnResponseStatus & { protocol?: Protocol }> {
+    return this._dwn.protocols.configure({
+      message    : { definition: this._definition },
+      encryption : options?.encryption,
+    });
+  }
+
+  /**
+   * 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`.
+   */
+  public async write<Path extends ProtocolPaths<D> & string>(
+    path : Path,
+    request : TypedWriteRequest<D, M, Path>,
+  ): Promise<TypedWriteResponse> {
+    const typeName = lastSegment(path);
+    const typeEntry = this._definition.types[typeName] as ProtocolType | undefined;
+
+    return this._dwn.records.write({
+      data       : request.data,
+      store      : request.store,
+      encryption : request.encryption,
+      message    : {
+        ...request.message,
+        protocol     : this._definition.protocol,
+        protocolPath : path,
+        schema       : typeEntry?.schema,
+        dataFormat   : request.message?.dataFormat ?? typeEntry?.dataFormats?.[0],
+      },
+    });
+  }
+
+  /**
+   * Query records at the given protocol path.
+   *
+   * @param path - The protocol path to query.
+   * @param request - Query options including optional filter, sort, and pagination.
+   */
+  public async query<Path extends ProtocolPaths<D> & string>(
+    path : Path,
+    request? : TypedQueryRequest,
+  ): Promise<TypedQueryResponse> {
+    const typeName = lastSegment(path);
+    const typeEntry = this._definition.types[typeName] as ProtocolType | undefined;
+
+    return this._dwn.records.query({
+      from       : request?.from,
+      protocol   : this._definition.protocol,
+      encryption : request?.encryption,
+      message    : {
+        filter: {
+          ...request?.filter,
+          protocol     : this._definition.protocol,
+          protocolPath : path,
+          schema       : typeEntry?.schema,
+        },
+        dateSort     : request?.dateSort,
+        pagination   : request?.pagination,
+        protocolRole : request?.protocolRole,
+      },
+    });
+  }
+
+  /**
+   * Read a single record at the given protocol path.
+   *
+   * @param path - The protocol path to read from.
+   * @param request - Read options including a filter to identify the record.
+   */
+  public async read<Path extends ProtocolPaths<D> & string>(
+    path : Path,
+    request : TypedReadRequest,
+  ): Promise<TypedReadResponse> {
+    const typeName = lastSegment(path);
+    const typeEntry = this._definition.types[typeName] as ProtocolType | undefined;
+
+    return this._dwn.records.read({
+      from       : request.from,
+      protocol   : this._definition.protocol,
+      encryption : request.encryption,
+      message    : {
+        filter: {
+          ...request.filter,
+          protocol     : this._definition.protocol,
+          protocolPath : path,
+          schema       : typeEntry?.schema,
+        },
+      },
+    });
+  }
+
+  /**
+   * Delete a record at the given protocol path.
+   *
+   * @param path - The protocol path (used for permission scoping).
+   * @param request - Delete options including the `recordId`.
+   */
+  public async delete<Path extends ProtocolPaths<D> & string>(
+    _path : Path,
+    request : TypedDeleteRequest,
+  ): Promise<DwnResponseStatus> {
+    return this._dwn.records.delete({
+      from     : request.from,
+      protocol : this._definition.protocol,
+      message  : {
+        recordId: request.recordId,
+      },
+    });
+  }
+
+  /**
+   * Subscribe to records at the given protocol path.
+   *
+   * @param path - The protocol path to subscribe to.
+   * @param request - Subscribe options including the subscription handler.
+   */
+  public async subscribe<Path extends ProtocolPaths<D> & string>(
+    path : Path,
+    request : TypedSubscribeRequest,
+  ): Promise<TypedSubscribeResponse> {
+    const typeName = lastSegment(path);
+    const typeEntry = this._definition.types[typeName] as ProtocolType | undefined;
+
+    return this._dwn.records.subscribe({
+      from                : request.from,
+      protocol            : this._definition.protocol,
+      encryption          : request.encryption,
+      subscriptionHandler : request.subscriptionHandler,
+      message             : {
+        filter: {
+          ...request.filter,
+          protocol     : this._definition.protocol,
+          protocolPath : path,
+          schema       : typeEntry?.schema,
+        },
+        protocolRole: request.protocolRole,
+      },
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the last segment of a slash-delimited path.
+ */
+function lastSegment(path: string): string {
+  const parts = path.split('/');
+  return parts[parts.length - 1];
+}

package/src/web5.ts

@@ -16,7 +16,8 @@ import type {
   Web5Agent,
 } from '@enbox/agent';
 
-import { DwnRegistrar, WalletConnect, Web5UserAgent } from '@enbox/agent';
+import { DwnRegistrar } from '@enbox/dwn-clients';
+import { WalletConnect, Web5UserAgent } from '@enbox/agent';
 
 import { DidApi } from './did-api.js';
 import { DwnApi } from './dwn-api.js';
@@ -380,7 +381,7 @@ export class Web5 {
                   purposes  : ['assertionMethod', 'authentication']
                 },
                 {
-                  algorithm : 'secp256k1',
+                  algorithm : 'X25519',
                   id        : 'enc',
                   purposes  : ['keyAgreement']
                 }