openvibe-sdk (contract types)

Generated at 2026-09-23 23:26:36 UTC from openvibe-contracts v0.33.0 and openvibe-sdk v0.5.0.

From types/contracts.d.ts (types only). Declarations are shown verbatim.

export type SubjectRef =
  | {
      type: "user";
      id: string;
    }
  | {
      type: "guest";
      id: string;
    }
  | {
      type: "app";
      id: string;
    }
  | {
      type: "mod";
      id: string;
    }
  | {
      type: "service" | "system";
      id: string;
    };

export type ServiceTokenClaims = {
  [k: string]: unknown | undefined;
} & {
  /**
   * Issuer; https://openvibe.network in production. Receivers pass the issuer they expect to verifyServiceToken().
   */
  iss: string;
  sub: string;
  actor_type: "service" | "app" | "mod";
  /**
   * @minItems 1
   */
  aud: [string, ...string[]];
  /**
   * Granted capability ids; a trailing .* grants a family.
   */
  cap: string[];
  /**
   * Namespace constraints, e.g. live.* or mod.example.*
   */
  ns?: string[];
  iat: number;
  exp: number;
  jti: string;
  /**
   * Developer project of an app principal (ADR-014). Services key tenancy by it. Absent on first-party service tokens.
   */
  project_id?: string;
  /**
   * Environment of an app principal. A receiver MUST refuse env=sandbox (401 token.sandbox_refused) unless it opted in to sandbox tokens. Absent on first-party service tokens, which are production.
   */
  env?: "sandbox" | "production";
  /**
   * The person who authorized an app through the authorization-code flow. Absent on client_credentials tokens.
   */
  on_behalf_of?: string;
  [k: string]: unknown | undefined;
};

export interface EntityRef {
  service: string;
  type: string;
  id: string;
  revision?: number;
  /**
   * Cached display label. Never authoritative.
   */
  label?: string;
}

export interface Problem {
  type: string;
  title: string;
  status: number;
  detail?: string;
  instance?: string;
  code: string;
  request_id?: string;
  trace_id?: string;
  errors?: {
    path?: string;
    message: string;
  }[];
  /**
   * Deprecated compatibility field: same text as title/detail for clients that read {error}.
   */
  error?: string;
  [k: string]: unknown | undefined;
}

export interface ServiceManifest {
  id: string;
  name?: string;
  version: string;
  status: "placeholder" | "alpha" | "beta" | "stable" | "degraded" | "retired";
  repository: string;
  domains: string[];
  publicOrigin?: string;
  health?: string;
  ready?: string;
  capabilities: string[];
  eventsProduced: string[];
  eventsConsumed: string[];
  namespacesOwned: string[];
  contractRanges?: {
    [k: string]: string | undefined;
  };
  notes?: string;
}

export interface Capability {
  id: string;
  version: string;
  owner: string;
  status: "planned" | "active" | "deprecated" | "retired";
  visibility: "public" | "partner" | "first-party" | "internal";
  description?: string;
  inputSchema?: string;
  outputSchema?: string;
  permissions: string[];
  resourceConstraints: ("namespace" | "owner" | "room_member" | "space_member" | "project" | "none")[];
  quotaClass: string;
  events: string[];
  /**
   * Current route(s) that perform this action today, e.g. 'POST /api/v1/:app/files'.
   */
  implementedBy?: string[];
}

export interface EventEnvelope {
  event_id: string;
  trace_id?: string;
  event_type: string;
  version: number;
  source: string;
  actor: SubjectRef;
  timestamp: string;
  priority?: "critical" | "important" | "low";
  visibility?: "public" | "subject" | "internal";
  subject: {
    type: string;
    id: string;
    revision?: number;
  };
  payload: {};
}

export interface ModuleNamespace {
  namespace: string;
  /**
   * Service that owns the namespace and may write it with network.modules.write.
   */
  owner: string;
  /**
   * Schema version stored with every record; a change needs a migration note.
   */
  version: number;
  description?: string;
  /**
   * JSON Schema (2020-12) every stored value must satisfy.
   */
  schema: {};
  /**
   * owner = the owning service with a token; user = the subject themselves.
   *
   * @minItems 1
   */
  writers: ["owner" | "user", ...("owner" | "user")[]];
  /**
   * Top-level fields anyone may read. Everything else is readable only by the subject and granted services.
   */
  publicFields: string[];
  quotaBytes: number;
  /**
   * What happens to records when the owning service or mod is retired.
   */
  onOwnerRemoved: "retain-readonly" | "delete-after-retention";
  retentionDays?: number;
  /**
   * How records of the previous version are upgraded.
   */
  migration?: string;
}

export interface ModuleRecord {
  subject: SubjectRef;
  namespace: string;
  version: number;
  revision: number;
  data: {};
  updated_at: string;
  /**
   * user:<subject> or svc:<service>
   */
  updated_by?: string;
}

export interface AppManifest {
  /**
   * The Network app id (its client_id). Its principal subject is app:<id>.
   */
  id: string;
  name: string;
  /**
   * Semantic version of this release.
   */
  version: string;
  description?: string;
  publisher: SubjectRef;
  /**
   * The Network project that owns the app. Tenancy in other services is keyed by it (ADR-014).
   */
  project_id: string;
  /**
   * The app's environment. Apps never change environment.
   */
  environment?: "sandbox" | "production";
  /**
   * Capability ids the app asks for (3+ segments). Only active public (or partner, by staff allowance) capabilities can ever be granted to apps.
   *
   * @maxItems 64
   */
  capabilities: string[];
  events?: {
    /**
     * Event types (or a trailing .* family) the app subscribes to.
     *
     * @maxItems 64
     */
    consumes?: string[];
  };
  /**
   * Informational copy of the redirect URIs registered in Network (Network's list is the authority).
   *
   * @maxItems 10
   */
  redirect_uris?:
    | []
    | [string]
    | [string, string]
    | [string, string, string]
    | [string, string, string, string]
    | [string, string, string, string, string]
    | [string, string, string, string, string, string]
    | [string, string, string, string, string, string, string]
    | [string, string, string, string, string, string, string, string]
    | [string, string, string, string, string, string, string, string, string]
    | [string, string, string, string, string, string, string, string, string, string];
  homepage?: string;
  repository?: string;
  /**
   * SPDX license expression.
   */
  license?: string;
  compatibility: {
    /**
     * Semver range of openvibe-contracts releases it was built against.
     */
    contracts: string;
    /**
     * Semver range of openvibe-sdk releases it uses.
     */
    sdk?: string;
  };
}