@tigmart/ai-types 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,237 @@
+/**
+ * Arbitrary key-value metadata that can be attached to any domain entity.
+ * Values are intentionally restricted to JSON-safe scalars so storage
+ * adapters can serialize without additional logic.
+ */
+type Metadata = Record<string, string | number | boolean | null>;
+
+/** The author role of a message in a conversation. */
+type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+/**
+ * Lifecycle status of a message.
+ *
+ * - pending   — created locally, not yet sent or acknowledged
+ * - streaming — assistant is actively writing (partial content)
+ * - done      — content is complete and stable
+ * - error     — delivery or generation failed; see `Message.error`
+ */
+type MessageStatus = 'pending' | 'streaming' | 'done' | 'error';
+interface TextPart {
+    type: 'text';
+    text: string;
+}
+interface ImagePart {
+    type: 'image';
+    /** Publicly accessible URL or a data: URI for inline images. */
+    url: string;
+    mimeType: string;
+    altText?: string;
+}
+interface FilePart {
+    type: 'file';
+    /** Publicly accessible URL to the uploaded file. */
+    url: string;
+    name: string;
+    mimeType: string;
+    /** File size in bytes. */
+    size: number;
+}
+/** A single piece of content within a message. */
+type MessagePart = TextPart | ImagePart | FilePart;
+interface Message {
+    id: string;
+    conversationId: string;
+    role: MessageRole;
+    /**
+     * Ordered list of content parts that make up this message.
+     * Most messages will have a single TextPart. Multi-modal messages
+     * may have an ImagePart or FilePart alongside text.
+     */
+    parts: MessagePart[];
+    status: MessageStatus;
+    /** Human-readable error description when status === 'error'. */
+    error?: string;
+    /** The model ID used to generate this message (assistant messages only). */
+    model?: string;
+    /** The provider ID used to generate this message (assistant messages only). */
+    providerId?: string;
+    /** Unix timestamp (ms) when the message was created. */
+    createdAt: number;
+    /** Unix timestamp (ms) when the message was last updated. */
+    updatedAt: number;
+    metadata: Metadata;
+}
+
+/**
+ * A conversation is a single chat thread.
+ * It belongs to an optional project and always has a provider + model assigned.
+ */
+interface Conversation {
+    id: string;
+    /** Null means the conversation is not grouped under any project. */
+    projectId: string | null;
+    title: string;
+    /**
+     * Optional system prompt for this specific conversation.
+     * If the conversation belongs to a project, this overrides the
+     * project's defaultSystemPrompt when set.
+     */
+    systemPrompt?: string;
+    /** ID of the provider selected for this conversation. */
+    providerId: string;
+    /** ID of the model (scoped to the provider) selected for this conversation. */
+    modelId: string;
+    /** Unix timestamp (ms) when the conversation was created. */
+    createdAt: number;
+    /** Unix timestamp (ms) when the conversation was last updated. */
+    updatedAt: number;
+    metadata: Metadata;
+}
+
+/**
+ * A project groups one or more conversations under a shared context.
+ * Defaults set here are applied when creating a new conversation
+ * inside the project, but each conversation can override them.
+ */
+interface Project {
+    id: string;
+    name: string;
+    description?: string;
+    /** Default provider ID applied to new conversations in this project. */
+    defaultProviderId?: string;
+    /** Default model ID applied to new conversations in this project. */
+    defaultModelId?: string;
+    /** Default system prompt applied to new conversations in this project. */
+    defaultSystemPrompt?: string;
+    /** Unix timestamp (ms) when the project was created. */
+    createdAt: number;
+    /** Unix timestamp (ms) when the project was last updated. */
+    updatedAt: number;
+    metadata: Metadata;
+}
+
+/**
+ * Describes what a specific model is capable of.
+ * Used by the UI to conditionally render controls (e.g. attach button)
+ * and by adapters to validate requests before sending.
+ */
+interface ModelCapabilities {
+    streaming: boolean;
+    /** Accepts image parts in messages. */
+    images: boolean;
+    /** Supports tool/function calling. */
+    tools: boolean;
+}
+/** A model offered by a provider. */
+interface Model {
+    id: string;
+    name: string;
+    /** Maximum combined input + output tokens. */
+    contextWindow: number;
+    capabilities: ModelCapabilities;
+}
+/**
+ * Static configuration describing a provider and its available models.
+ * This is the registration shape — not the runtime adapter.
+ */
+interface ProviderConfig {
+    id: string;
+    name: string;
+    models: Model[];
+}
+
+/**
+ * Token consumption reported by the provider at the end of a stream.
+ * Fields are optional because not all providers return full breakdowns.
+ */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * A single chunk emitted by a provider adapter during streaming.
+ * Discriminated by `type`.
+ *
+ * - delta  — partial text content to append to the current message
+ * - done   — stream has ended cleanly; optional token usage provided
+ * - error  — stream ended with an error from the provider
+ */
+type StreamChunk = {
+    type: 'delta';
+    content: string;
+} | {
+    type: 'done';
+    usage?: TokenUsage;
+} | {
+    type: 'error';
+    error: string;
+};
+/** Options forwarded to the provider when starting a stream. */
+interface StreamOptions {
+    /** AbortSignal to cancel an in-progress stream. */
+    signal?: AbortSignal;
+    maxTokens?: number;
+    temperature?: number;
+}
+
+/**
+ * Pluggable storage contract for all platform entities.
+ *
+ * Implementations must handle their own serialization.
+ * All operations are async to support both synchronous backends
+ * (e.g. localStorage wrapped in Promises) and remote backends.
+ *
+ * V1 ships with a LocalStorageAdapter.
+ * Later: IndexedDBAdapter, RESTAdapter.
+ */
+interface ChatStorage {
+    getProjects(): Promise<Project[]>;
+    saveProject(project: Project): Promise<void>;
+    deleteProject(id: string): Promise<void>;
+    /**
+     * Returns all conversations, optionally filtered by project.
+     * Pass `null` to get conversations that are not in any project.
+     * Omit the argument to get all conversations regardless of project.
+     */
+    getConversations(projectId?: string | null): Promise<Conversation[]>;
+    saveConversation(conversation: Conversation): Promise<void>;
+    deleteConversation(id: string): Promise<void>;
+    /** Returns all messages for a conversation in insertion order. */
+    getMessages(conversationId: string): Promise<Message[]>;
+    /** Appends a new message. Throws if the message ID already exists. */
+    appendMessage(conversationId: string, message: Message): Promise<void>;
+    /** Replaces an existing message in full (used to apply streaming deltas). */
+    updateMessage(conversationId: string, message: Message): Promise<void>;
+    deleteMessage(conversationId: string, messageId: string): Promise<void>;
+}
+
+/**
+ * The contract every LLM provider adapter must implement.
+ * Implementations live in @topsoft/ai-core (server-side only).
+ *
+ * The adapter receives normalized Message objects and returns an
+ * AsyncIterable of StreamChunks. Mapping to/from provider-specific
+ * wire formats is the adapter's responsibility.
+ */
+interface ProviderAdapter {
+    /** Unique identifier for the provider (e.g. 'openai', 'anthropic'). */
+    readonly id: string;
+    /** Human-readable display name (e.g. 'OpenAI'). */
+    readonly name: string;
+    /** All models this provider exposes. */
+    readonly models: Model[];
+    /**
+     * Start a streaming completion.
+     *
+     * @param messages  Full conversation history in normalized format.
+     * @param modelId   One of the model IDs from `this.models`.
+     * @param options   Optional per-request controls.
+     * @returns         AsyncIterable of StreamChunks. Callers must consume
+     *                  the iterable to completion or call signal.abort()
+     *                  to cancel early.
+     */
+    stream(messages: Message[], modelId: string, options?: StreamOptions): AsyncIterable<StreamChunk>;
+}
+
+export type { ChatStorage, Conversation, FilePart, ImagePart, Message, MessagePart, MessageRole, MessageStatus, Metadata, Model, ModelCapabilities, Project, ProviderAdapter, ProviderConfig, StreamChunk, StreamOptions, TextPart, TokenUsage };

package/dist/index.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Arbitrary key-value metadata that can be attached to any domain entity.
+ * Values are intentionally restricted to JSON-safe scalars so storage
+ * adapters can serialize without additional logic.
+ */
+type Metadata = Record<string, string | number | boolean | null>;
+
+/** The author role of a message in a conversation. */
+type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+/**
+ * Lifecycle status of a message.
+ *
+ * - pending   — created locally, not yet sent or acknowledged
+ * - streaming — assistant is actively writing (partial content)
+ * - done      — content is complete and stable
+ * - error     — delivery or generation failed; see `Message.error`
+ */
+type MessageStatus = 'pending' | 'streaming' | 'done' | 'error';
+interface TextPart {
+    type: 'text';
+    text: string;
+}
+interface ImagePart {
+    type: 'image';
+    /** Publicly accessible URL or a data: URI for inline images. */
+    url: string;
+    mimeType: string;
+    altText?: string;
+}
+interface FilePart {
+    type: 'file';
+    /** Publicly accessible URL to the uploaded file. */
+    url: string;
+    name: string;
+    mimeType: string;
+    /** File size in bytes. */
+    size: number;
+}
+/** A single piece of content within a message. */
+type MessagePart = TextPart | ImagePart | FilePart;
+interface Message {
+    id: string;
+    conversationId: string;
+    role: MessageRole;
+    /**
+     * Ordered list of content parts that make up this message.
+     * Most messages will have a single TextPart. Multi-modal messages
+     * may have an ImagePart or FilePart alongside text.
+     */
+    parts: MessagePart[];
+    status: MessageStatus;
+    /** Human-readable error description when status === 'error'. */
+    error?: string;
+    /** The model ID used to generate this message (assistant messages only). */
+    model?: string;
+    /** The provider ID used to generate this message (assistant messages only). */
+    providerId?: string;
+    /** Unix timestamp (ms) when the message was created. */
+    createdAt: number;
+    /** Unix timestamp (ms) when the message was last updated. */
+    updatedAt: number;
+    metadata: Metadata;
+}
+
+/**
+ * A conversation is a single chat thread.
+ * It belongs to an optional project and always has a provider + model assigned.
+ */
+interface Conversation {
+    id: string;
+    /** Null means the conversation is not grouped under any project. */
+    projectId: string | null;
+    title: string;
+    /**
+     * Optional system prompt for this specific conversation.
+     * If the conversation belongs to a project, this overrides the
+     * project's defaultSystemPrompt when set.
+     */
+    systemPrompt?: string;
+    /** ID of the provider selected for this conversation. */
+    providerId: string;
+    /** ID of the model (scoped to the provider) selected for this conversation. */
+    modelId: string;
+    /** Unix timestamp (ms) when the conversation was created. */
+    createdAt: number;
+    /** Unix timestamp (ms) when the conversation was last updated. */
+    updatedAt: number;
+    metadata: Metadata;
+}
+
+/**
+ * A project groups one or more conversations under a shared context.
+ * Defaults set here are applied when creating a new conversation
+ * inside the project, but each conversation can override them.
+ */
+interface Project {
+    id: string;
+    name: string;
+    description?: string;
+    /** Default provider ID applied to new conversations in this project. */
+    defaultProviderId?: string;
+    /** Default model ID applied to new conversations in this project. */
+    defaultModelId?: string;
+    /** Default system prompt applied to new conversations in this project. */
+    defaultSystemPrompt?: string;
+    /** Unix timestamp (ms) when the project was created. */
+    createdAt: number;
+    /** Unix timestamp (ms) when the project was last updated. */
+    updatedAt: number;
+    metadata: Metadata;
+}
+
+/**
+ * Describes what a specific model is capable of.
+ * Used by the UI to conditionally render controls (e.g. attach button)
+ * and by adapters to validate requests before sending.
+ */
+interface ModelCapabilities {
+    streaming: boolean;
+    /** Accepts image parts in messages. */
+    images: boolean;
+    /** Supports tool/function calling. */
+    tools: boolean;
+}
+/** A model offered by a provider. */
+interface Model {
+    id: string;
+    name: string;
+    /** Maximum combined input + output tokens. */
+    contextWindow: number;
+    capabilities: ModelCapabilities;
+}
+/**
+ * Static configuration describing a provider and its available models.
+ * This is the registration shape — not the runtime adapter.
+ */
+interface ProviderConfig {
+    id: string;
+    name: string;
+    models: Model[];
+}
+
+/**
+ * Token consumption reported by the provider at the end of a stream.
+ * Fields are optional because not all providers return full breakdowns.
+ */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * A single chunk emitted by a provider adapter during streaming.
+ * Discriminated by `type`.
+ *
+ * - delta  — partial text content to append to the current message
+ * - done   — stream has ended cleanly; optional token usage provided
+ * - error  — stream ended with an error from the provider
+ */
+type StreamChunk = {
+    type: 'delta';
+    content: string;
+} | {
+    type: 'done';
+    usage?: TokenUsage;
+} | {
+    type: 'error';
+    error: string;
+};
+/** Options forwarded to the provider when starting a stream. */
+interface StreamOptions {
+    /** AbortSignal to cancel an in-progress stream. */
+    signal?: AbortSignal;
+    maxTokens?: number;
+    temperature?: number;
+}
+
+/**
+ * Pluggable storage contract for all platform entities.
+ *
+ * Implementations must handle their own serialization.
+ * All operations are async to support both synchronous backends
+ * (e.g. localStorage wrapped in Promises) and remote backends.
+ *
+ * V1 ships with a LocalStorageAdapter.
+ * Later: IndexedDBAdapter, RESTAdapter.
+ */
+interface ChatStorage {
+    getProjects(): Promise<Project[]>;
+    saveProject(project: Project): Promise<void>;
+    deleteProject(id: string): Promise<void>;
+    /**
+     * Returns all conversations, optionally filtered by project.
+     * Pass `null` to get conversations that are not in any project.
+     * Omit the argument to get all conversations regardless of project.
+     */
+    getConversations(projectId?: string | null): Promise<Conversation[]>;
+    saveConversation(conversation: Conversation): Promise<void>;
+    deleteConversation(id: string): Promise<void>;
+    /** Returns all messages for a conversation in insertion order. */
+    getMessages(conversationId: string): Promise<Message[]>;
+    /** Appends a new message. Throws if the message ID already exists. */
+    appendMessage(conversationId: string, message: Message): Promise<void>;
+    /** Replaces an existing message in full (used to apply streaming deltas). */
+    updateMessage(conversationId: string, message: Message): Promise<void>;
+    deleteMessage(conversationId: string, messageId: string): Promise<void>;
+}
+
+/**
+ * The contract every LLM provider adapter must implement.
+ * Implementations live in @topsoft/ai-core (server-side only).
+ *
+ * The adapter receives normalized Message objects and returns an
+ * AsyncIterable of StreamChunks. Mapping to/from provider-specific
+ * wire formats is the adapter's responsibility.
+ */
+interface ProviderAdapter {
+    /** Unique identifier for the provider (e.g. 'openai', 'anthropic'). */
+    readonly id: string;
+    /** Human-readable display name (e.g. 'OpenAI'). */
+    readonly name: string;
+    /** All models this provider exposes. */
+    readonly models: Model[];
+    /**
+     * Start a streaming completion.
+     *
+     * @param messages  Full conversation history in normalized format.
+     * @param modelId   One of the model IDs from `this.models`.
+     * @param options   Optional per-request controls.
+     * @returns         AsyncIterable of StreamChunks. Callers must consume
+     *                  the iterable to completion or call signal.abort()
+     *                  to cancel early.
+     */
+    stream(messages: Message[], modelId: string, options?: StreamOptions): AsyncIterable<StreamChunk>;
+}
+
+export type { ChatStorage, Conversation, FilePart, ImagePart, Message, MessagePart, MessageRole, MessageStatus, Metadata, Model, ModelCapabilities, Project, ProviderAdapter, ProviderConfig, StreamChunk, StreamOptions, TextPart, TokenUsage };

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+module.exports = __toCommonJS(index_exports);

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@tigmart/ai-types",
+  "version": "0.0.1",
+  "description": "Shared TypeScript types for the AI chat platform",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0"
+  }
+}