@enbox/protocols 0.1.0

package/src/lists.ts

@@ -0,0 +1,163 @@
+/**
+ * Lists Protocol — flexible list management with folders and collaboration.
+ *
+ * Supports both nesting patterns:
+ * - **Fixed-depth folders**: `folder/folder/folder` (3 levels max)
+ * - **Flat items with tag-based hierarchy**: `list/item` with `parentItemId` tag
+ *
+ * Composes with Social Graph for friend-scoped read access and
+ * defines a `collaborator` role for write access to shared lists.
+ *
+ * @module
+ */
+
+import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+
+import { defineProtocol } from '@enbox/api';
+
+// ---------------------------------------------------------------------------
+// Data types
+// ---------------------------------------------------------------------------
+
+/** Data shape for a list record. */
+export type ListData = {
+  name: string;
+  description?: string;
+  icon?: string;
+  listType: 'todo' | 'bookmarks' | 'reading' | 'custom';
+};
+
+/** Data shape for a list item. */
+export type ItemData = {
+  title: string;
+  url?: string;
+  note?: string;
+  completed?: boolean;
+  sortOrder?: number;
+};
+
+/** Data shape for a folder record. */
+export type FolderData = {
+  name: string;
+  icon?: string;
+  sortOrder?: number;
+};
+
+/** Data shape for a collaborator record. */
+export type CollaboratorData = {
+  did: string;
+  alias?: string;
+};
+
+/** Data shape for a comment on a list item. */
+export type CommentData = {
+  text: string;
+};
+
+// ---------------------------------------------------------------------------
+// Schema map
+// ---------------------------------------------------------------------------
+
+/** Maps protocol type names to their TypeScript data shapes. */
+export type ListsSchemaMap = {
+  list: ListData;
+  item: ItemData;
+  folder: FolderData;
+  collaborator: CollaboratorData;
+  comment: CommentData;
+};
+
+// ---------------------------------------------------------------------------
+// Protocol definition
+// ---------------------------------------------------------------------------
+
+export const ListsDefinition = {
+  protocol  : 'https://enbox.org/protocols/lists',
+  published : false,
+  uses      : {
+    social: 'https://enbox.org/protocols/social-graph',
+  },
+  types: {
+    list: {
+      schema      : 'https://enbox.org/schemas/lists/list',
+      dataFormats : ['application/json'],
+    },
+    item: {
+      schema      : 'https://enbox.org/schemas/lists/item',
+      dataFormats : ['application/json'],
+    },
+    folder: {
+      schema      : 'https://enbox.org/schemas/lists/folder',
+      dataFormats : ['application/json'],
+    },
+    collaborator: {
+      schema      : 'https://enbox.org/schemas/lists/collaborator',
+      dataFormats : ['application/json'],
+    },
+    comment: {
+      schema      : 'https://enbox.org/schemas/lists/comment',
+      dataFormats : ['application/json'],
+    },
+  },
+  structure: {
+    list: {
+      $actions: [
+        { role: 'social:friend', can: ['read'] },
+      ],
+      $tags: {
+        $requiredTags       : ['listType'],
+        $allowUndefinedTags : false,
+        listType            : { type: 'string', enum: ['todo', 'bookmarks', 'reading', 'custom'] },
+      },
+      item: {
+        $actions: [
+          { role: 'social:friend', can: ['read'] },
+          { role: 'list/collaborator', can: ['create', 'read', 'update', 'delete'] },
+        ],
+        $tags: {
+          $allowUndefinedTags : true,
+          parentItemId        : { type: 'string' },
+        },
+        comment: {
+          $actions: [
+            { role: 'list/collaborator', can: ['create', 'read'] },
+          ],
+        },
+      },
+      collaborator: {
+        $role    : true,
+        $actions : [
+          { who: 'anyone', can: ['read'] },
+        ],
+        $tags: {
+          $requiredTags       : ['did'],
+          $allowUndefinedTags : false,
+          did                 : { type: 'string' },
+        },
+      },
+    },
+    folder: {
+      $actions : [],
+      $tags    : {
+        $allowUndefinedTags : true,
+        sortOrder           : { type: 'number' },
+      },
+      folder: {
+        $actions : [],
+        folder   : {
+          $actions: [],
+        },
+      },
+    },
+  },
+} as const satisfies ProtocolDefinition;
+
+// ---------------------------------------------------------------------------
+// Typed protocol export
+// ---------------------------------------------------------------------------
+
+/** Typed Lists protocol for use with `dwn.using()`. */
+export const ListsProtocol = defineProtocol(
+  ListsDefinition,
+  {} as ListsSchemaMap,
+);

package/src/preferences.ts

@@ -0,0 +1,120 @@
+/**
+ * Preferences Protocol — user configuration and settings.
+ *
+ * Stores theme, locale, privacy, and notification preferences.
+ * Fully owner-only (no external reads). The `privacy` type uses
+ * `encryptionRequired` for at-rest encryption of sensitive settings.
+ *
+ * @module
+ */
+
+import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+
+import { defineProtocol } from '@enbox/api';
+
+// ---------------------------------------------------------------------------
+// Data types
+// ---------------------------------------------------------------------------
+
+/** Data shape for theme preferences. */
+export type ThemeData = {
+  mode: 'light' | 'dark' | 'system';
+  accentColor?: string;
+  fontSize?: 'small' | 'medium' | 'large';
+};
+
+/** Data shape for locale preferences. */
+export type LocaleData = {
+  language: string;
+  region?: string;
+  timezone?: string;
+  dateFormat?: string;
+  hourCycle?: '12h' | '24h';
+};
+
+/** Data shape for privacy preferences. */
+export type PrivacyData = {
+  cookieConsent: {
+    analytics: boolean;
+    marketing: boolean;
+    functional: boolean;
+  };
+  shareUsageData: boolean;
+};
+
+/** Data shape for notification preferences. */
+export type NotificationData = {
+  channel: string;
+  enabled: boolean;
+  quietHoursStart?: string;
+  quietHoursEnd?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Schema map
+// ---------------------------------------------------------------------------
+
+/** Maps protocol type names to their TypeScript data shapes. */
+export type PreferencesSchemaMap = {
+  theme: ThemeData;
+  locale: LocaleData;
+  privacy: PrivacyData;
+  notification: NotificationData;
+};
+
+// ---------------------------------------------------------------------------
+// Protocol definition
+// ---------------------------------------------------------------------------
+
+export const PreferencesDefinition = {
+  protocol  : 'https://enbox.org/protocols/preferences',
+  published : false,
+  types     : {
+    theme: {
+      schema      : 'https://enbox.org/schemas/preferences/theme',
+      dataFormats : ['application/json'],
+    },
+    locale: {
+      schema      : 'https://enbox.org/schemas/preferences/locale',
+      dataFormats : ['application/json'],
+    },
+    privacy: {
+      schema             : 'https://enbox.org/schemas/preferences/privacy',
+      dataFormats        : ['application/json'],
+      encryptionRequired : true,
+    },
+    notification: {
+      schema      : 'https://enbox.org/schemas/preferences/notification',
+      dataFormats : ['application/json'],
+    },
+  },
+  structure: {
+    theme: {
+      $actions: [],
+    },
+    locale: {
+      $actions: [],
+    },
+    privacy: {
+      $actions: [],
+    },
+    notification: {
+      $actions : [],
+      $tags    : {
+        $requiredTags       : ['channel'],
+        $allowUndefinedTags : false,
+        channel             : { type: 'string' },
+      },
+    },
+  },
+} as const satisfies ProtocolDefinition;
+
+// ---------------------------------------------------------------------------
+// Typed protocol export
+// ---------------------------------------------------------------------------
+
+/** Typed Preferences protocol for use with `dwn.using()`. */
+export const PreferencesProtocol = defineProtocol(
+  PreferencesDefinition,
+  {} as PreferencesSchemaMap,
+);

package/src/profile.ts

@@ -0,0 +1,116 @@
+/**
+ * Profile Protocol — public and semi-private identity information.
+ *
+ * Supports a published profile record, avatar (binary), links, and
+ * private notes visible only to friends (via Social Graph composition).
+ *
+ * @module
+ */
+
+import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+
+import { defineProtocol } from '@enbox/api';
+
+// ---------------------------------------------------------------------------
+// Data types
+// ---------------------------------------------------------------------------
+
+/** Data shape for a profile record. */
+export type ProfileData = {
+  displayName: string;
+  bio?: string;
+  location?: string;
+  website?: string;
+  pronouns?: string;
+};
+
+/** Avatar is stored as binary data (Blob). */
+export type AvatarData = Blob;
+
+/** Data shape for a link record (e.g. social links). */
+export type LinkData = {
+  url: string;
+  title: string;
+  icon?: string;
+  sortOrder?: number;
+};
+
+/** Data shape for a private note (visible only to friends). */
+export type PrivateNoteData = {
+  content: string;
+};
+
+// ---------------------------------------------------------------------------
+// Schema map
+// ---------------------------------------------------------------------------
+
+/** Maps protocol type names to their TypeScript data shapes. */
+export type ProfileSchemaMap = {
+  profile: ProfileData;
+  avatar: AvatarData;
+  link: LinkData;
+  privateNote: PrivateNoteData;
+};
+
+// ---------------------------------------------------------------------------
+// Protocol definition
+// ---------------------------------------------------------------------------
+
+export const ProfileDefinition = {
+  protocol  : 'https://enbox.org/protocols/profile',
+  published : true,
+  uses      : {
+    social: 'https://enbox.org/protocols/social-graph',
+  },
+  types: {
+    profile: {
+      schema      : 'https://enbox.org/schemas/profile/profile',
+      dataFormats : ['application/json'],
+    },
+    avatar: {
+      dataFormats: ['image/png', 'image/jpeg', 'image/gif', 'image/webp'],
+    },
+    link: {
+      schema      : 'https://enbox.org/schemas/profile/link',
+      dataFormats : ['application/json'],
+    },
+    privateNote: {
+      schema      : 'https://enbox.org/schemas/profile/private-note',
+      dataFormats : ['application/json'],
+    },
+  },
+  structure: {
+    profile: {
+      $size    : { max: 10000 },
+      $actions : [
+        { who: 'anyone', can: ['read'] },
+      ],
+      avatar: {
+        $size    : { max: 1048576 },
+        $actions : [
+          { who: 'anyone', can: ['read'] },
+        ],
+      },
+      link: {
+        $actions: [
+          { who: 'anyone', can: ['read'] },
+        ],
+      },
+    },
+    privateNote: {
+      $actions: [
+        { role: 'social:friend', can: ['read'] },
+      ],
+    },
+  },
+} as const satisfies ProtocolDefinition;
+
+// ---------------------------------------------------------------------------
+// Typed protocol export
+// ---------------------------------------------------------------------------
+
+/** Typed Profile protocol for use with `dwn.using()`. */
+export const ProfileProtocol = defineProtocol(
+  ProfileDefinition,
+  {} as ProfileSchemaMap,
+);

package/src/social-graph.ts

@@ -0,0 +1,131 @@
+/**
+ * Social Graph Protocol — foundation protocol for relationship management.
+ *
+ * Provides friend, block, group, and member types with role-based access.
+ * Other protocols compose with this via `uses` to leverage the `friend` role
+ * for cross-protocol authorization.
+ *
+ * @module
+ */
+
+import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+
+import { defineProtocol } from '@enbox/api';
+
+// ---------------------------------------------------------------------------
+// Data types
+// ---------------------------------------------------------------------------
+
+/** Data shape for a friend record. */
+export type FriendData = {
+  did: string;
+  alias?: string;
+  note?: string;
+};
+
+/** Data shape for a block record. */
+export type BlockData = {
+  did: string;
+  reason?: string;
+};
+
+/** Data shape for a group record. */
+export type GroupData = {
+  name: string;
+  description?: string;
+  icon?: string;
+};
+
+/** Data shape for a group member record. */
+export type MemberData = {
+  did: string;
+  alias?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Schema map
+// ---------------------------------------------------------------------------
+
+/** Maps protocol type names to their TypeScript data shapes. */
+export type SocialGraphSchemaMap = {
+  friend: FriendData;
+  block: BlockData;
+  group: GroupData;
+  member: MemberData;
+};
+
+// ---------------------------------------------------------------------------
+// Protocol definition
+// ---------------------------------------------------------------------------
+
+export const SocialGraphDefinition = {
+  protocol  : 'https://enbox.org/protocols/social-graph',
+  published : true,
+  types     : {
+    friend: {
+      schema      : 'https://enbox.org/schemas/social-graph/friend',
+      dataFormats : ['application/json'],
+    },
+    block: {
+      schema      : 'https://enbox.org/schemas/social-graph/block',
+      dataFormats : ['application/json'],
+    },
+    group: {
+      schema      : 'https://enbox.org/schemas/social-graph/group',
+      dataFormats : ['application/json'],
+    },
+    member: {
+      schema      : 'https://enbox.org/schemas/social-graph/member',
+      dataFormats : ['application/json'],
+    },
+  },
+  structure: {
+    friend: {
+      $role    : true,
+      $actions : [
+        { who: 'anyone', can: ['create'] },
+        { who: 'author', of: 'friend', can: ['read'] },
+      ],
+      $tags: {
+        $requiredTags       : ['did'],
+        $allowUndefinedTags : false,
+        did                 : { type: 'string' },
+      },
+    },
+    block: {
+      $actions: [
+        { who: 'anyone', can: ['create'] },
+      ],
+      $tags: {
+        $requiredTags       : ['did'],
+        $allowUndefinedTags : false,
+        did                 : { type: 'string' },
+      },
+    },
+    group: {
+      $actions: [
+        { who: 'anyone', can: ['read'] },
+      ],
+      member: {
+        $actions: [
+          { who: 'anyone', can: ['read'] },
+        ],
+        $tags: {
+          $requiredTags       : ['did'],
+          $allowUndefinedTags : false,
+          did                 : { type: 'string' },
+        },
+      },
+    },
+  },
+} as const satisfies ProtocolDefinition;
+
+// ---------------------------------------------------------------------------
+// Typed protocol export
+// ---------------------------------------------------------------------------
+
+/** Typed Social Graph protocol for use with `dwn.using()`. */
+export const SocialGraphProtocol = defineProtocol(
+  SocialGraphDefinition,
+  {} as SocialGraphSchemaMap,
+);

package/src/status.ts

@@ -0,0 +1,86 @@
+/**
+ * Status Protocol — ephemeral status updates with reactions.
+ *
+ * Uses the `published` flag on individual records to control visibility:
+ * published statuses are readable by anyone, unpublished ones only by friends.
+ * Composes with Social Graph for friend-scoped access and reactions.
+ *
+ * @module
+ */
+
+import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+
+import { defineProtocol } from '@enbox/api';
+
+// ---------------------------------------------------------------------------
+// Data types
+// ---------------------------------------------------------------------------
+
+/** Data shape for a status update. */
+export type StatusData = {
+  text: string;
+  emoji?: string;
+  activity?: 'online' | 'away' | 'busy' | 'offline';
+  expiresAt?: string;
+};
+
+/** Data shape for a reaction to a status. */
+export type ReactionData = {
+  emoji: string;
+};
+
+// ---------------------------------------------------------------------------
+// Schema map
+// ---------------------------------------------------------------------------
+
+/** Maps protocol type names to their TypeScript data shapes. */
+export type StatusSchemaMap = {
+  status: StatusData;
+  reaction: ReactionData;
+};
+
+// ---------------------------------------------------------------------------
+// Protocol definition
+// ---------------------------------------------------------------------------
+
+export const StatusDefinition = {
+  protocol  : 'https://enbox.org/protocols/status',
+  published : true,
+  uses      : {
+    social: 'https://enbox.org/protocols/social-graph',
+  },
+  types: {
+    status: {
+      schema      : 'https://enbox.org/schemas/status/status',
+      dataFormats : ['application/json'],
+    },
+    reaction: {
+      schema      : 'https://enbox.org/schemas/status/reaction',
+      dataFormats : ['application/json'],
+    },
+  },
+  structure: {
+    status: {
+      $size    : { max: 5000 },
+      $actions : [
+        { who: 'anyone', can: ['read'] },
+        { role: 'social:friend', can: ['read'] },
+      ],
+      reaction: {
+        $actions: [
+          { role: 'social:friend', can: ['create', 'read', 'delete'] },
+        ],
+      },
+    },
+  },
+} as const satisfies ProtocolDefinition;
+
+// ---------------------------------------------------------------------------
+// Typed protocol export
+// ---------------------------------------------------------------------------
+
+/** Typed Status protocol for use with `dwn.using()`. */
+export const StatusProtocol = defineProtocol(
+  StatusDefinition,
+  {} as StatusSchemaMap,
+);