@oxyhq/core 17.0.3 → 17.1.0

package/dist/types/index.d.ts

@@ -39,7 +39,7 @@ export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHand
 export { normalizeProfileLinks } from './utils/profileLinks';
 export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type { PublicApplication, ConnectedApp, } from './mixins/OxyServices.connectedApps';
-export type { AccountKind, OrganizationCategory, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
+export type { AccountKind, OrganizationCategory, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, UserCreatableAccountKind, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
 export { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts';
 export { buildUserDid } from './mixins/OxyServices.identity';
 export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, RotateKeyProof, RotateKeyOptions, RotateKeyResult, } from './mixins/OxyServices.identity';

package/dist/types/mixins/OxyServices.accounts.d.ts

@@ -131,10 +131,12 @@ export interface ListAccountsOptions {
      */
     tree?: boolean;
 }
+/** Kinds a signed-in user may create via `POST /accounts`. Channels are service-provisioned only. */
+export type UserCreatableAccountKind = 'organization' | 'project' | 'bot';
 /** Input accepted by `createAccount`. */
 export interface CreateAccountInput {
-    /** Classification of the new account. `personal` accounts are not created here. */
-    kind: AccountKind;
+    /** Classification of the new account. `personal` and `channel` are not creatable here. */
+    kind: UserCreatableAccountKind;
     /**
      * Parent account `_id` to nest the new account under. Omitted → the API roots
      * it under the caller's personal account.
@@ -142,9 +144,16 @@ export interface CreateAccountInput {
     parentAccountId?: string;
     /** Unique handle for the account (shares the `User.username` unique index). */
     username: string;
+    /**
+     * A managed account (organization / project / bot / channel) has a TITLE, not
+     * a given-and-family name, so it sets `displayName` — the explicit
+     * `name_display` column — and leaves `first`/`last` unset. Splitting a title
+     * on whitespace into `first`/`last` is what this replaced.
+     */
     name?: {
         first?: string;
         last?: string;
+        displayName?: string;
     };
     bio?: string;
     avatar?: string;
@@ -154,15 +163,47 @@ export interface CreateAccountInput {
 /** Input accepted by `updateAccount`. Tree placement changes go through `/move`. */
 export interface UpdateAccountInput {
     username?: string;
+    /**
+     * Same shape as `CreateAccountInput['name']`. On update, an EMPTY STRING in
+     * `displayName` clears the explicit name and falls back to the composed
+     * `first`/`last`; omitting the key leaves the stored value untouched. The two
+     * are not interchangeable.
+     */
     name?: {
         first?: string;
         last?: string;
+        displayName?: string;
     };
     bio?: string | null;
     avatar?: string | null;
     /** Clears the category when `null`; only valid on `kind: 'organization'`. */
     organizationCategory?: OrganizationCategory | null;
 }
+/** Input accepted by `provisionChannelAccount` (service token + `accounts:provision`). */
+export interface ProvisionChannelInput {
+    /** Personal account `_id` whose tree owns the new channel. */
+    ownerUserId: string;
+    username: string;
+    name?: {
+        first?: string;
+        last?: string;
+        displayName?: string;
+    };
+    bio?: string;
+    description?: string;
+    avatar?: string;
+}
+/** Input accepted by `provisionChannelMember` (service token + `accounts:provision`). */
+export interface ProvisionChannelMemberInput {
+    memberUserId: string;
+    role: Exclude<AccountRole, 'owner'>;
+    inherit?: boolean;
+}
+/** Result of `provisionChannelAccount`. */
+export interface ProvisionChannelResult {
+    account: User;
+    membership: AccountMember;
+}
 /** Input accepted by `inviteAccountMember`. The owner role cannot be invited. */
 export interface InviteAccountMemberInput {
     /**
@@ -430,6 +471,11 @@ export interface SwitchAccountResult extends SessionLoginResponse {
 }
 export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
+        /**
+         * Inherited from the auth mixin at runtime. Declared here so service-scoped
+         * account provisioning methods can call it with correct typing.
+         */
+        makeServiceRequest: <R = unknown>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: unknown, userId?: string) => Promise<R>;
         /**
          * List the accounts the caller can access: their own personal (root)
          * account, accounts they own, and accounts shared with them (including
@@ -483,6 +529,23 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
          * @param data - Account configuration: kind, optional parent, and profile.
          */
         createAccount(data: CreateAccountInput): Promise<AccountNode>;
+        /**
+         * Mint a `channel` account under `ownerUserId` via service auth
+         * (`accounts:provision` scope). Requires `configureServiceAuth` first.
+         */
+        provisionChannelAccount(data: ProvisionChannelInput): Promise<ProvisionChannelResult>;
+        /**
+         * Grant membership on a channel account via service auth
+         * (`accounts:provision` scope).
+         */
+        provisionChannelMember(channelAccountId: string, data: ProvisionChannelMemberInput): Promise<{
+            member: AccountMember;
+        }>;
+        /**
+         * Revoke membership on a channel account via service auth
+         * (`accounts:provision` scope).
+         */
+        revokeChannelMember(channelAccountId: string, memberUserId: string): Promise<AccountSuccessResult>;
         /**
          * Update an account's mutable profile fields. Tree placement changes
          * (reparenting) go through the dedicated move endpoint, not here.

package/dist/types/models/interfaces.d.ts

@@ -1,4 +1,4 @@
-import type { OrganizationCategory, UserNameResponse, UserRelationship, ThemePreference } from '@oxyhq/contracts';
+import type { AccountKind, OrganizationCategory, UserNameResponse, UserRelationship, ThemePreference } from '@oxyhq/contracts';
 export interface OxyConfig {
     baseURL: string;
     cloudURL?: string;
@@ -118,6 +118,22 @@ export interface User {
         following?: number;
     };
     accountExpiresAfterInactivityDays?: number | null;
+    /**
+     * Account-graph classification — WHAT this account is.
+     *
+     * ORTHOGONAL to `type` below, and easy to confuse with it: `type` says where
+     * the account lives and how it is driven (`local` / `federated` / `agent` /
+     * `automated`), `kind` says what it IS (`personal` / `organization` /
+     * `project` / `bot` / `channel`). A federated channel is `type: 'federated'`
+     * AND `kind: 'channel'`; neither value substitutes for the other.
+     *
+     * This is what a consumer rendering authored content reads to tell a
+     * channel's post from a person's — a channel is the author, so there is no
+     * second identity to carry alongside the user.
+     *
+     * Absent should be read as `personal` (the column's default), not as unknown.
+     */
+    kind?: AccountKind;
     type?: 'local' | 'federated' | 'agent' | 'automated';
     isFederated?: boolean;
     /** Allow sharing this user's content on the fediverse. Defaults to true. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "17.0.3",
+  "version": "17.1.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -115,7 +115,7 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.21.0",
+    "@oxyhq/contracts": "^0.22.0",
     "@oxyhq/protocol": "^0.1.6",
     "@scure/bip39": "^1.6.0",
     "@types/elliptic": "^6.4.18",

package/src/index.ts

@@ -136,8 +136,12 @@ export type {
     AccountCredentialWithSecret,
     RotateAccountCredentialResult,
     ListAccountsOptions,
+    UserCreatableAccountKind,
     CreateAccountInput,
     UpdateAccountInput,
+    ProvisionChannelInput,
+    ProvisionChannelMemberInput,
+    ProvisionChannelResult,
     InviteAccountMemberInput,
     UpdateAccountMemberInput,
     TransferAccountOwnershipInput,

package/src/mixins/OxyServices.accounts.ts

@@ -146,10 +146,13 @@ export interface ListAccountsOptions {
   tree?: boolean;
 }
 
+/** Kinds a signed-in user may create via `POST /accounts`. Channels are service-provisioned only. */
+export type UserCreatableAccountKind = 'organization' | 'project' | 'bot';
+
 /** Input accepted by `createAccount`. */
 export interface CreateAccountInput {
-  /** Classification of the new account. `personal` accounts are not created here. */
-  kind: AccountKind;
+  /** Classification of the new account. `personal` and `channel` are not creatable here. */
+  kind: UserCreatableAccountKind;
   /**
    * Parent account `_id` to nest the new account under. Omitted → the API roots
    * it under the caller's personal account.
@@ -157,7 +160,13 @@ export interface CreateAccountInput {
   parentAccountId?: string;
   /** Unique handle for the account (shares the `User.username` unique index). */
   username: string;
-  name?: { first?: string; last?: string };
+  /**
+   * A managed account (organization / project / bot / channel) has a TITLE, not
+   * a given-and-family name, so it sets `displayName` — the explicit
+   * `name_display` column — and leaves `first`/`last` unset. Splitting a title
+   * on whitespace into `first`/`last` is what this replaced.
+   */
+  name?: { first?: string; last?: string; displayName?: string };
   bio?: string;
   avatar?: string;
   /** Meaningful only when `kind` is `organization`. */
@@ -167,13 +176,43 @@ export interface CreateAccountInput {
 /** Input accepted by `updateAccount`. Tree placement changes go through `/move`. */
 export interface UpdateAccountInput {
   username?: string;
-  name?: { first?: string; last?: string };
+  /**
+   * Same shape as `CreateAccountInput['name']`. On update, an EMPTY STRING in
+   * `displayName` clears the explicit name and falls back to the composed
+   * `first`/`last`; omitting the key leaves the stored value untouched. The two
+   * are not interchangeable.
+   */
+  name?: { first?: string; last?: string; displayName?: string };
   bio?: string | null;
   avatar?: string | null;
   /** Clears the category when `null`; only valid on `kind: 'organization'`. */
   organizationCategory?: OrganizationCategory | null;
 }
 
+/** Input accepted by `provisionChannelAccount` (service token + `accounts:provision`). */
+export interface ProvisionChannelInput {
+  /** Personal account `_id` whose tree owns the new channel. */
+  ownerUserId: string;
+  username: string;
+  name?: { first?: string; last?: string; displayName?: string };
+  bio?: string;
+  description?: string;
+  avatar?: string;
+}
+
+/** Input accepted by `provisionChannelMember` (service token + `accounts:provision`). */
+export interface ProvisionChannelMemberInput {
+  memberUserId: string;
+  role: Exclude<AccountRole, 'owner'>;
+  inherit?: boolean;
+}
+
+/** Result of `provisionChannelAccount`. */
+export interface ProvisionChannelResult {
+  account: User;
+  membership: AccountMember;
+}
+
 /** Input accepted by `inviteAccountMember`. The owner role cannot be invited. */
 export interface InviteAccountMemberInput {
   /**
@@ -482,6 +521,17 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
       super(...(args as [any]));
     }
 
+    /**
+     * Inherited from the auth mixin at runtime. Declared here so service-scoped
+     * account provisioning methods can call it with correct typing.
+     */
+    declare makeServiceRequest: <R = unknown>(
+      method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+      url: string,
+      data?: unknown,
+      userId?: string,
+    ) => Promise<R>;
+
     // =========================================================================
     // Accounts
     // =========================================================================
@@ -620,6 +670,59 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
       }
     }
 
+    /**
+     * Mint a `channel` account under `ownerUserId` via service auth
+     * (`accounts:provision` scope). Requires `configureServiceAuth` first.
+     */
+    async provisionChannelAccount(data: ProvisionChannelInput): Promise<ProvisionChannelResult> {
+      try {
+        return await this.makeServiceRequest<ProvisionChannelResult>(
+          'POST',
+          '/accounts/service/channels',
+          data,
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Grant membership on a channel account via service auth
+     * (`accounts:provision` scope).
+     */
+    async provisionChannelMember(
+      channelAccountId: string,
+      data: ProvisionChannelMemberInput,
+    ): Promise<{ member: AccountMember }> {
+      try {
+        return await this.makeServiceRequest<{ member: AccountMember }>(
+          'POST',
+          `/accounts/service/channels/${encodeURIComponent(channelAccountId)}/members`,
+          data,
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Revoke membership on a channel account via service auth
+     * (`accounts:provision` scope).
+     */
+    async revokeChannelMember(
+      channelAccountId: string,
+      memberUserId: string,
+    ): Promise<AccountSuccessResult> {
+      try {
+        return await this.makeServiceRequest<AccountSuccessResult>(
+          'DELETE',
+          `/accounts/service/channels/${encodeURIComponent(channelAccountId)}/members/${encodeURIComponent(memberUserId)}`,
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * Update an account's mutable profile fields. Tree placement changes
      * (reparenting) go through the dedicated move endpoint, not here.

package/src/models/interfaces.ts

@@ -1,4 +1,5 @@
 import type {
+  AccountKind,
   OrganizationCategory,
   UserNameResponse,
   UserRelationship,
@@ -134,6 +135,22 @@ export interface User {
     following?: number;
   };
   accountExpiresAfterInactivityDays?: number | null; // Days of inactivity before account expires (null = never expire)
+  /**
+   * Account-graph classification — WHAT this account is.
+   *
+   * ORTHOGONAL to `type` below, and easy to confuse with it: `type` says where
+   * the account lives and how it is driven (`local` / `federated` / `agent` /
+   * `automated`), `kind` says what it IS (`personal` / `organization` /
+   * `project` / `bot` / `channel`). A federated channel is `type: 'federated'`
+   * AND `kind: 'channel'`; neither value substitutes for the other.
+   *
+   * This is what a consumer rendering authored content reads to tell a
+   * channel's post from a person's — a channel is the author, so there is no
+   * second identity to carry alongside the user.
+   *
+   * Absent should be read as `personal` (the column's default), not as unknown.
+   */
+  kind?: AccountKind;
   // User type and external account support
   type?: 'local' | 'federated' | 'agent' | 'automated';
   isFederated?: boolean;