makelore/shared/data-service.ts

export type DataServiceUsage = {
  document_count: number;
  total_bytes: number;
};

export type DataServiceCollection = {
  name: string;
  document_count: number;
  total_bytes: number;
  created_at: string;
};

export type DataServiceLimits = {
  max_collections: number;
  max_documents: number;
  max_total_bytes: number;
  max_document_bytes: number;
  list_default_limit: number;
  list_max_limit: number;
  list_max_data_bytes: number;
  mutations_per_minute: number;
};

export type DataServiceInstanceState = {
  instance_id: string;
  project_id: string;
  collections: DataServiceCollection[];
  usage: DataServiceUsage;
  limits: DataServiceLimits;
  created_at: string;
  updated_at: string;
};

export type DataServiceInstanceList = {
  items: DataServiceInstanceState[];
  total: number;
  instance_limit: number;
};

export type DataServiceCollectionRemoval = {
  removed: boolean;
  usage: DataServiceUsage;
};

export type DataServiceInstanceRemoval = {
  removed: boolean;
};

export type DataServiceDocument = {
  id: string;
  data: Record<string, unknown>;
  revision: number;
  created_at: string;
  updated_at: string;
};

export type DataServiceDocumentList = {
  items: DataServiceDocument[];
  next_cursor: string | null;
  limit: number;
};

export type DataServiceErrorContext = Record<string, string | number>;

export type PluginBillingMode =
  | 'included'
  | 'platform_metered'
  | 'external_account';

/**
 * A closed billing projection.  Token Point amounts stay decimal strings all
 * the way through the client boundary; no UI or adapter is allowed to invent
 * an amount or a terminal receipt.
 */
export type CapabilityBillingReceiptV1 =
  | {
      mode: 'unknown' | PluginBillingMode;
      status: 'not_started';
    }
  | {
      mode: 'included';
      status: 'included';
    }
  | {
      mode: 'external_account';
      status: 'external';
    }
  | {
      mode: 'platform_metered';
      status: 'reserved' | 'dispatched' | 'released' | 'pending_review' | 'expired';
      reserved_points: string;
      actual_points?: string;
      usage_amount?: number;
      unit?: string;
    }
  | {
      mode: 'platform_metered';
      status: 'settled' | 'refunded';
      reserved_points: string;
      actual_points: string;
      usage_amount?: number;
      unit?: string;
    };

export interface CapabilityResultV1<T = unknown> {
  schema: 'makelore-capability.v1';
  plugin_id: string;
  plugin_version: string;
  capability_id: string;
  operation: string;
  request_id: string;
  success: boolean;
  status: number;
  code: string | null;
  error: string | null;
  retryable: boolean;
  retry_after_seconds?: number;
  context?: Readonly<Record<string, string | number>>;
  billing: CapabilityBillingReceiptV1;
  payload_schema: string;
  data: T | null;
}

export const DATA_SERVICE_PI_TOOL_NAMES = [
  'data_service_configure',
  'data_service_inspect',
  'data_service_list_projects',
  'data_service_get_document',
  'data_service_list_documents',
  'data_service_put_document',
  'data_service_delete_document',
  'data_service_remove_collection',
  'data_service_reset',
  'data_service_remove_project',
] as const;

export type DataServicePiToolName = (typeof DATA_SERVICE_PI_TOOL_NAMES)[number];

export type DataServiceHostResult<T> = {
  success: boolean;
  status: number;
  code: string | null;
  error: string | null;
  retryable: boolean;
  retry_after_seconds?: number;
  context?: DataServiceErrorContext;
  data: T | null;
};

export type DataServiceToolData =
  | DataServiceInstanceState
  | DataServiceInstanceList
  | DataServiceDocument
  | DataServiceDocumentList
  | DataServiceCollectionRemoval
  | DataServiceInstanceRemoval;

/** @deprecated Use the registry-owned capability envelope with this payload schema. */
export type DataServiceToolDetailsV1 = CapabilityResultV1<DataServiceToolData> & {
  payload_schema: 'data-service.v1';
};

export type DataServicePutDocumentInput = {
  collection: string;
  document_id: string;
  data: Record<string, unknown>;
  if_revision?: number;
};

export type DataServiceDocumentTargetInput = {
  collection: string;
  document_id: string;
  if_revision?: number;
};

export type DataServiceCollectionTargetInput = {
  collection: string;
  confirmed: true;
};

export type DataServiceConfirmationInput = {
  confirmed: true;
};