@npm-safe/core-dsh 1.0.5

package/dist/store/schema.d.ts

@@ -0,0 +1,42 @@
+/**
+ * SQLite DDL schema and migration helpers for @npm-safe/core.
+ *
+ * This module is a pure SQL-string + types module. It MUST NOT import or
+ * execute better-sqlite3; consumers (e.g. the store layer) are responsible
+ * for running the SQL through `Database#prepare().run()`.
+ */
+/**
+ * Full DDL for the core database. Contains 6 application tables plus the
+ * `_migrations` bookkeeping table used by the migration runner.
+ *
+ * Tables:
+ *  1. packages          - cached npm package metadata
+ *  2. package_versions  - per-version info
+ *  3. security_reports  - scan results (static + llm)
+ *  4. watchlist         - user-tracked packages
+ *  5. settings          - key-value configuration
+ *  6. translations      - cached translation results
+ *  7. _migrations       - migration tracking (internal)
+ */
+export declare const SCHEMA_SQL = "\n-- 1. packages table - cached npm package metadata\nCREATE TABLE IF NOT EXISTS packages (\n  name                TEXT PRIMARY KEY,\n  latest_version      TEXT NOT NULL,\n  description         TEXT DEFAULT '',\n  homepage            TEXT DEFAULT '',\n  repository          TEXT DEFAULT '',\n  registry_data       TEXT DEFAULT '{}',  -- JSON blob of raw registry response\n  cached_at           TEXT NOT NULL DEFAULT (datetime('now')),\n  ttl_until           TEXT NOT NULL       -- cache expiry timestamp\n);\n\n-- 2. package_versions table - version info\nCREATE TABLE IF NOT EXISTS package_versions (\n  package_name  TEXT NOT NULL REFERENCES packages(name) ON DELETE CASCADE,\n  version       TEXT NOT NULL,\n  publish_time  TEXT,\n  has_readme    INTEGER NOT NULL DEFAULT 0,\n  integrity     TEXT,\n  PRIMARY KEY (package_name, version)\n);\n\n-- 3. security_reports table - scan results\nCREATE TABLE IF NOT EXISTS security_reports (\n  id            INTEGER PRIMARY KEY AUTOINCREMENT,\n  package_name  TEXT NOT NULL REFERENCES packages(name) ON DELETE CASCADE,\n  version       TEXT NOT NULL,\n  scan_type     TEXT NOT NULL CHECK(scan_type IN ('static', 'llm')),\n  overall_score INTEGER NOT NULL CHECK(overall_score >= 0 AND overall_score <= 100),\n  findings_json TEXT DEFAULT '[]',   -- JSON array of ScanFinding objects\n  summary       TEXT DEFAULT '',\n  scanned_at    TEXT NOT NULL DEFAULT (datetime('now')),\n  UNIQUE(package_name, version, scan_type)\n);\n\n-- 4. watchlist table - user-tracked packages\nCREATE TABLE IF NOT EXISTS watchlist (\n  package_name  TEXT PRIMARY KEY REFERENCES packages(name) ON DELETE CASCADE,\n  added_at      TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\n-- 5. settings table - key-value configuration\nCREATE TABLE IF NOT EXISTS settings (\n  key   TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\n\n-- 6. translations table - cached translations\nCREATE TABLE IF NOT EXISTS translations (\n  source_hash     TEXT PRIMARY KEY,\n  source_text     TEXT NOT NULL,\n  target_lang     TEXT NOT NULL,\n  translated_text TEXT NOT NULL,\n  provider        TEXT NOT NULL,\n  created_at      TEXT NOT NULL DEFAULT (datetime('now'))\n);\nCREATE INDEX IF NOT EXISTS idx_translations_lang ON translations(target_lang);\n\n-- 7. _migrations table - migration tracking\nCREATE TABLE IF NOT EXISTS _migrations (\n  id          INTEGER PRIMARY KEY AUTOINCREMENT,\n  name        TEXT NOT NULL UNIQUE,\n  applied_at  TEXT NOT NULL DEFAULT (datetime('now'))\n);\n";
+/**
+ * Returns ordered list of migration file names to apply.
+ *
+ * Migrations are applied in order; each name must be unique. The initial
+ * migration (`001_initial.sql`) is expected to create every table in
+ * {@link SCHEMA_SQL} via {@link getInitialMigration}.
+ */
+export declare function getMigrationList(): string[];
+/**
+ * Returns the SQL for the `check_history` migration: a table recording every
+ * check performed by the CLI or the desktop extension so the GUI can load
+ * history straight from the shared database.
+ */
+export declare function getCheckHistoryMigration(): string;
+/**
+ * Returns the SQL for the initial migration. This is the same DDL as
+ * {@link SCHEMA_SQL}, wrapped for the migration system so the runner can
+ * record it under the `001_initial.sql` name.
+ */
+export declare function getInitialMigration(): string;
+//# sourceMappingURL=schema.d.ts.map

package/dist/store/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/store/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,67EAiEtB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAK3C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAYjD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}

package/dist/store/schema.js

@@ -0,0 +1,126 @@
+/**
+ * SQLite DDL schema and migration helpers for @npm-safe/core.
+ *
+ * This module is a pure SQL-string + types module. It MUST NOT import or
+ * execute better-sqlite3; consumers (e.g. the store layer) are responsible
+ * for running the SQL through `Database#prepare().run()`.
+ */
+/**
+ * Full DDL for the core database. Contains 6 application tables plus the
+ * `_migrations` bookkeeping table used by the migration runner.
+ *
+ * Tables:
+ *  1. packages          - cached npm package metadata
+ *  2. package_versions  - per-version info
+ *  3. security_reports  - scan results (static + llm)
+ *  4. watchlist         - user-tracked packages
+ *  5. settings          - key-value configuration
+ *  6. translations      - cached translation results
+ *  7. _migrations       - migration tracking (internal)
+ */
+export const SCHEMA_SQL = `
+-- 1. packages table - cached npm package metadata
+CREATE TABLE IF NOT EXISTS packages (
+  name                TEXT PRIMARY KEY,
+  latest_version      TEXT NOT NULL,
+  description         TEXT DEFAULT '',
+  homepage            TEXT DEFAULT '',
+  repository          TEXT DEFAULT '',
+  registry_data       TEXT DEFAULT '{}',  -- JSON blob of raw registry response
+  cached_at           TEXT NOT NULL DEFAULT (datetime('now')),
+  ttl_until           TEXT NOT NULL       -- cache expiry timestamp
+);
+
+-- 2. package_versions table - version info
+CREATE TABLE IF NOT EXISTS package_versions (
+  package_name  TEXT NOT NULL REFERENCES packages(name) ON DELETE CASCADE,
+  version       TEXT NOT NULL,
+  publish_time  TEXT,
+  has_readme    INTEGER NOT NULL DEFAULT 0,
+  integrity     TEXT,
+  PRIMARY KEY (package_name, version)
+);
+
+-- 3. security_reports table - scan results
+CREATE TABLE IF NOT EXISTS security_reports (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  package_name  TEXT NOT NULL REFERENCES packages(name) ON DELETE CASCADE,
+  version       TEXT NOT NULL,
+  scan_type     TEXT NOT NULL CHECK(scan_type IN ('static', 'llm')),
+  overall_score INTEGER NOT NULL CHECK(overall_score >= 0 AND overall_score <= 100),
+  findings_json TEXT DEFAULT '[]',   -- JSON array of ScanFinding objects
+  summary       TEXT DEFAULT '',
+  scanned_at    TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE(package_name, version, scan_type)
+);
+
+-- 4. watchlist table - user-tracked packages
+CREATE TABLE IF NOT EXISTS watchlist (
+  package_name  TEXT PRIMARY KEY REFERENCES packages(name) ON DELETE CASCADE,
+  added_at      TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- 5. settings table - key-value configuration
+CREATE TABLE IF NOT EXISTS settings (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+-- 6. translations table - cached translations
+CREATE TABLE IF NOT EXISTS translations (
+  source_hash     TEXT PRIMARY KEY,
+  source_text     TEXT NOT NULL,
+  target_lang     TEXT NOT NULL,
+  translated_text TEXT NOT NULL,
+  provider        TEXT NOT NULL,
+  created_at      TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_translations_lang ON translations(target_lang);
+
+-- 7. _migrations table - migration tracking
+CREATE TABLE IF NOT EXISTS _migrations (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  name        TEXT NOT NULL UNIQUE,
+  applied_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+`;
+/**
+ * Returns ordered list of migration file names to apply.
+ *
+ * Migrations are applied in order; each name must be unique. The initial
+ * migration (`001_initial.sql`) is expected to create every table in
+ * {@link SCHEMA_SQL} via {@link getInitialMigration}.
+ */
+export function getMigrationList() {
+    return [
+        '001_initial.sql',
+        '002_check_history.sql',
+    ];
+}
+/**
+ * Returns the SQL for the `check_history` migration: a table recording every
+ * check performed by the CLI or the desktop extension so the GUI can load
+ * history straight from the shared database.
+ */
+export function getCheckHistoryMigration() {
+    return `
+-- 8. check_history table - persistent check history
+CREATE TABLE IF NOT EXISTS check_history (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  package_name  TEXT NOT NULL,
+  level         TEXT NOT NULL,
+  score         INTEGER NOT NULL CHECK(score >= 0 AND score <= 100),
+  timestamp     TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_check_history_timestamp ON check_history(timestamp DESC);
+`;
+}
+/**
+ * Returns the SQL for the initial migration. This is the same DDL as
+ * {@link SCHEMA_SQL}, wrapped for the migration system so the runner can
+ * record it under the `001_initial.sql` name.
+ */
+export function getInitialMigration() {
+    return SCHEMA_SQL;
+}
+//# sourceMappingURL=schema.js.map

package/dist/store/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/store/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiEzB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO;QACL,iBAAiB;QACjB,uBAAuB;KACxB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO;;;;;;;;;;CAUR,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/translator/provider.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Translator provider interface and adapter skeletons for @npm-safe/core.
+ *
+ * This module defines the {@link TranslatorProvider} interface that all
+ * translation backends must implement, together with skeleton adapters for
+ * DeepL and OpenAI-compatible APIs. The skeletons are ready for Phase 5
+ * integration — they validate credentials but throw
+ * {@link ProviderNotConfigured} or {@link TranslationError} with a "not yet
+ * implemented" message instead of making actual API calls.
+ *
+ * @module translator/provider
+ */
+import { TranslationResult, TranslatorConfig } from './types.js';
+/**
+ * Interface that every translation provider adapter must implement.
+ *
+ * Adapters are stateless beyond their configuration (API key, base URL,
+ * model) and may be shared across requests.
+ */
+export interface TranslatorProvider {
+    /** Human-readable name of the provider (e.g. `'DeepL'`, `'OpenAI'`). */
+    readonly name: string;
+    /**
+     * Translate text from a source language to a target language.
+     *
+     * @param text - The text to translate.
+     * @param targetLang - Target language code (e.g. `'zh-CN'`, `'fr'`).
+     * @param sourceLang - Optional source language code. When omitted the
+     *   provider may auto-detect the source language.
+     * @returns A promise resolving to the translation result.
+     * @throws {ProviderNotConfigured} When the provider has no API key.
+     * @throws {TranslationError} When the request fails at the network or
+     *   provider level.
+     */
+    translate(text: string, targetLang: string, sourceLang?: string): Promise<TranslationResult>;
+    /**
+     * Verify that the provider is reachable and the configured credentials
+     * are valid.
+     *
+     * @returns A promise resolving to `true` when the connection succeeds,
+     *   `false` when the provider is not configured.
+     * @throws {TranslationError} When the connection test fails at the
+     *   network or provider level.
+     */
+    testConnection(): Promise<boolean>;
+}
+/**
+ * Adapter for the DeepL translation API.
+ *
+ * This is a skeleton implementation for Phase 5. Construction requires an
+ * optional `apiKey`; without one, both {@link DeepLAdapter.translate} and
+ * {@link DeepLAdapter.testConnection} throw {@link ProviderNotConfigured}.
+ * With a key they throw {@link TranslationError} with a "not yet implemented"
+ * message.
+ */
+export declare class DeepLAdapter implements TranslatorProvider {
+    readonly name = "DeepL";
+    private readonly apiKey?;
+    private readonly baseUrl;
+    /**
+     * @param config.apiKey - DeepL API key (optional; required at call time).
+     * @param config.baseUrl - DeepL API base URL. Defaults to the free-tier
+     *   endpoint `https://api-free.deepl.com`.
+     */
+    constructor(config: {
+        apiKey?: string;
+        baseUrl?: string;
+    });
+    /**
+     * Translate text via DeepL.
+     *
+     * Phase 5: This method will POST to `${this.baseUrl}/v2/translate` with
+     * an `Authorization: DeepL-Auth-Key ${this.apiKey}` header.
+     *
+     * @param text - Text to translate.
+     * @param targetLang - Target language code.
+     * @param sourceLang - Optional source language code.
+     * @throws {ProviderNotConfigured} When no API key has been provided.
+     * @throws {TranslationError} Always — implementation is deferred to Phase 5.
+     */
+    translate(text: string, targetLang: string, sourceLang?: string): Promise<TranslationResult>;
+    /**
+     * Test the connection to the DeepL API.
+     *
+     * @returns `false` when no API key is configured (no test attempted).
+     * @throws {TranslationError} Always when an API key is present —
+     *   implementation is deferred to Phase 5.
+     */
+    testConnection(): Promise<boolean>;
+}
+/**
+ * Adapter for OpenAI-compatible chat completion APIs used for translation.
+ *
+ * This is a skeleton implementation for Phase 5. Construction requires an
+ * optional `apiKey`; without one, both {@link OpenAIAdapter.translate} and
+ * {@link OpenAIAdapter.testConnection} throw {@link ProviderNotConfigured}.
+ * With a key they throw {@link TranslationError} with a "not yet implemented"
+ * message.
+ */
+export declare class OpenAIAdapter implements TranslatorProvider {
+    readonly name = "OpenAI";
+    private readonly apiKey?;
+    private readonly baseUrl;
+    private readonly model;
+    /**
+     * @param config.apiKey - OpenAI API key (optional; required at call time).
+     * @param config.baseUrl - OpenAI API base URL. Defaults to
+     *   `https://api.openai.com/v1`.
+     * @param config.model - Model identifier for chat completions. Defaults to
+     *   `gpt-4o-mini`.
+     */
+    constructor(config: {
+        apiKey?: string;
+        baseUrl?: string;
+        model?: string;
+    });
+    /**
+     * Translate text via an OpenAI-compatible chat completion API.
+     *
+     * Phase 5: This method will POST to `${this.baseUrl}/chat/completions`
+     * with a system prompt instructing the model to translate, sending the
+     * given text as the user message.
+     *
+     * @param text - Text to translate.
+     * @param targetLang - Target language code.
+     * @param sourceLang - Optional source language code (passed as context
+     *   to the model; not used for auto-detection since LLMs do not return
+     *   a detected language).
+     * @throws {ProviderNotConfigured} When no API key has been provided.
+     * @throws {TranslationError} Always — implementation is deferred to Phase 5.
+     */
+    translate(text: string, targetLang: string, sourceLang?: string): Promise<TranslationResult>;
+    /**
+     * Test the connection to the OpenAI API.
+     *
+     * @returns `false` when no API key is configured (no test attempted).
+     * @throws {TranslationError} Always when an API key is present —
+     *   implementation is deferred to Phase 5.
+     */
+    testConnection(): Promise<boolean>;
+}
+/**
+ * Create a translator provider instance from a configuration object.
+ *
+ * @param config - Complete translator configuration including the target
+ *   provider type and any required credentials.
+ * @returns A provider adapter instance matching the configured type.
+ * @throws {TranslationError} When the requested provider type is
+ *   `LibreTranslate` (not yet implemented).
+ */
+export declare function createTranslator(config: TranslatorConfig): TranslatorProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/translator/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/translator/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAIjB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;OAWG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE9B;;;;;;;;OAQG;IACH,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAa,YAAW,kBAAkB;IACrD,QAAQ,CAAC,IAAI,WAAW;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;OAIG;gBACS,MAAM,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAKzD;;;;;;;;;;;OAWG;IACG,SAAS,CACb,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,CAAC;IAY7B;;;;;;OAMG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;CAQzC;AAED;;;;;;;;GAQG;AACH,qBAAa,aAAc,YAAW,kBAAkB;IACtD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;;;;OAMG;gBACS,MAAM,EAAE;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB;IAMD;;;;;;;;;;;;;;OAcG;IACG,SAAS,CACb,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,CAAC;IAe7B;;;;;;OAMG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;CAQzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,CAmB7E"}

package/dist/translator/provider.js

@@ -0,0 +1,159 @@
+/**
+ * Translator provider interface and adapter skeletons for @npm-safe/core.
+ *
+ * This module defines the {@link TranslatorProvider} interface that all
+ * translation backends must implement, together with skeleton adapters for
+ * DeepL and OpenAI-compatible APIs. The skeletons are ready for Phase 5
+ * integration — they validate credentials but throw
+ * {@link ProviderNotConfigured} or {@link TranslationError} with a "not yet
+ * implemented" message instead of making actual API calls.
+ *
+ * @module translator/provider
+ */
+import { TranslatorProviderType, ProviderNotConfigured, TranslationError, } from './types.js';
+/**
+ * Adapter for the DeepL translation API.
+ *
+ * This is a skeleton implementation for Phase 5. Construction requires an
+ * optional `apiKey`; without one, both {@link DeepLAdapter.translate} and
+ * {@link DeepLAdapter.testConnection} throw {@link ProviderNotConfigured}.
+ * With a key they throw {@link TranslationError} with a "not yet implemented"
+ * message.
+ */
+export class DeepLAdapter {
+    name = 'DeepL';
+    apiKey;
+    baseUrl;
+    /**
+     * @param config.apiKey - DeepL API key (optional; required at call time).
+     * @param config.baseUrl - DeepL API base URL. Defaults to the free-tier
+     *   endpoint `https://api-free.deepl.com`.
+     */
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl ?? 'https://api-free.deepl.com';
+    }
+    /**
+     * Translate text via DeepL.
+     *
+     * Phase 5: This method will POST to `${this.baseUrl}/v2/translate` with
+     * an `Authorization: DeepL-Auth-Key ${this.apiKey}` header.
+     *
+     * @param text - Text to translate.
+     * @param targetLang - Target language code.
+     * @param sourceLang - Optional source language code.
+     * @throws {ProviderNotConfigured} When no API key has been provided.
+     * @throws {TranslationError} Always — implementation is deferred to Phase 5.
+     */
+    async translate(text, targetLang, sourceLang) {
+        if (!this.apiKey) {
+            throw new ProviderNotConfigured('DeepL', 'No API key provided. Configure it in Settings.');
+        }
+        // Phase 5: Implement actual API call
+        // POST ${this.baseUrl}/v2/translate with Authorization: DeepL-Auth-Key ${this.apiKey}
+        throw new TranslationError('DeepL translation not yet implemented', 'DeepL');
+    }
+    /**
+     * Test the connection to the DeepL API.
+     *
+     * @returns `false` when no API key is configured (no test attempted).
+     * @throws {TranslationError} Always when an API key is present —
+     *   implementation is deferred to Phase 5.
+     */
+    async testConnection() {
+        if (!this.apiKey)
+            return false;
+        // Phase 5: Implement actual connection test
+        throw new TranslationError('DeepL testConnection not yet implemented', 'DeepL');
+    }
+}
+/**
+ * Adapter for OpenAI-compatible chat completion APIs used for translation.
+ *
+ * This is a skeleton implementation for Phase 5. Construction requires an
+ * optional `apiKey`; without one, both {@link OpenAIAdapter.translate} and
+ * {@link OpenAIAdapter.testConnection} throw {@link ProviderNotConfigured}.
+ * With a key they throw {@link TranslationError} with a "not yet implemented"
+ * message.
+ */
+export class OpenAIAdapter {
+    name = 'OpenAI';
+    apiKey;
+    baseUrl;
+    model;
+    /**
+     * @param config.apiKey - OpenAI API key (optional; required at call time).
+     * @param config.baseUrl - OpenAI API base URL. Defaults to
+     *   `https://api.openai.com/v1`.
+     * @param config.model - Model identifier for chat completions. Defaults to
+     *   `gpt-4o-mini`.
+     */
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl ?? 'https://api.openai.com/v1';
+        this.model = config.model ?? 'gpt-4o-mini';
+    }
+    /**
+     * Translate text via an OpenAI-compatible chat completion API.
+     *
+     * Phase 5: This method will POST to `${this.baseUrl}/chat/completions`
+     * with a system prompt instructing the model to translate, sending the
+     * given text as the user message.
+     *
+     * @param text - Text to translate.
+     * @param targetLang - Target language code.
+     * @param sourceLang - Optional source language code (passed as context
+     *   to the model; not used for auto-detection since LLMs do not return
+     *   a detected language).
+     * @throws {ProviderNotConfigured} When no API key has been provided.
+     * @throws {TranslationError} Always — implementation is deferred to Phase 5.
+     */
+    async translate(text, targetLang, sourceLang) {
+        if (!this.apiKey) {
+            throw new ProviderNotConfigured('OpenAI', 'No API key provided. Configure it in Settings.');
+        }
+        // Phase 5: Implement actual API call
+        // POST ${this.baseUrl}/chat/completions with system prompt for translation
+        throw new TranslationError('OpenAI translation not yet implemented', 'OpenAI');
+    }
+    /**
+     * Test the connection to the OpenAI API.
+     *
+     * @returns `false` when no API key is configured (no test attempted).
+     * @throws {TranslationError} Always when an API key is present —
+     *   implementation is deferred to Phase 5.
+     */
+    async testConnection() {
+        if (!this.apiKey)
+            return false;
+        // Phase 5: Implement actual connection test
+        throw new TranslationError('OpenAI testConnection not yet implemented', 'OpenAI');
+    }
+}
+/**
+ * Create a translator provider instance from a configuration object.
+ *
+ * @param config - Complete translator configuration including the target
+ *   provider type and any required credentials.
+ * @returns A provider adapter instance matching the configured type.
+ * @throws {TranslationError} When the requested provider type is
+ *   `LibreTranslate` (not yet implemented).
+ */
+export function createTranslator(config) {
+    switch (config.provider) {
+        case TranslatorProviderType.DeepL:
+            return new DeepLAdapter({
+                apiKey: config.apiKey,
+                baseUrl: config.baseUrl,
+            });
+        case TranslatorProviderType.OpenAI:
+            return new OpenAIAdapter({
+                apiKey: config.apiKey,
+                baseUrl: config.baseUrl,
+                model: config.model,
+            });
+        case TranslatorProviderType.LibreTranslate:
+            throw new TranslationError('LibreTranslate support not yet implemented', 'LibreTranslate');
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/translator/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/translator/provider.ts"],"names":[],"mappings":"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"}

package/dist/translator/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Type definitions for the translator provider system.
+ *
+ * This module defines the provider enumeration, configuration schemas,
+ * result types, and typed error classes used by the translator adapters
+ * defined in {@link ./provider.ts}.
+ *
+ * @module translator/types
+ */
+/**
+ * Supported translation provider backends.
+ *
+ * Each enum member corresponds to a concrete adapter implementation in
+ * {@link ../translator/provider.ts}.
+ */
+export declare enum TranslatorProviderType {
+    /** DeepL translation API (api-free.deepl.com or api.deepl.com). */
+    DeepL = "deepL",
+    /** OpenAI-compatible chat completion API for translation. */
+    OpenAI = "openAI",
+    /** Self-hosted LibreTranslate instance. */
+    LibreTranslate = "libreTranslate"
+}
+/**
+ * Result of a translation request.
+ */
+export interface TranslationResult {
+    /** The translated text in the target language. */
+    readonly translatedText: string;
+    /**
+     * Language code of the source text as detected by the provider, if the
+     * provider supports automatic source-language detection.
+     */
+    readonly detectedSourceLang?: string;
+    /** Usage metering information, if reported by the provider. */
+    readonly usage?: {
+        /** Number of characters billed for the request. */
+        readonly characters: number;
+    };
+}
+/**
+ * Configuration for initialising a translator provider adapter.
+ */
+export interface TranslatorConfig {
+    /** Which backend provider to use. */
+    readonly provider: TranslatorProviderType;
+    /** API key for the provider. May be omitted if the provider is configured
+     *  elsewhere (e.g. environment variables) or does not require one. */
+    readonly apiKey?: string;
+    /** Base URL of the provider's API endpoint. Defaults are specific to each
+     *  adapter. */
+    readonly baseUrl?: string;
+    /** Model identifier, used only by OpenAI-compatible providers. */
+    readonly model?: string;
+    /** Default target language code (e.g. `'zh-CN'`, `'fr'`). */
+    readonly targetLang: string;
+}
+/**
+ * Error thrown when a translator provider was selected but not configured
+ * with the required credentials.
+ */
+export declare class ProviderNotConfigured extends Error {
+    /**
+     * @param provider - Human-readable provider name (e.g. `'DeepL'`).
+     * @param reason - Explanation of what configuration is missing.
+     */
+    constructor(provider: string, reason: string);
+}
+/**
+ * Error thrown when a translation request fails at the network or provider
+ * level (timeout, non-2xx response, malformed reply, etc.).
+ */
+export declare class TranslationError extends Error {
+    readonly provider: string;
+    readonly statusCode?: number | undefined;
+    /**
+     * @param message - Human-readable error description.
+     * @param provider - Name of the provider that produced the error.
+     * @param statusCode - HTTP status code from the provider, if applicable.
+     */
+    constructor(message: string, provider: string, statusCode?: number | undefined);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/translator/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/translator/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,oBAAY,sBAAsB;IAChC,mEAAmE;IACnE,KAAK,UAAU;IACf,6DAA6D;IAC7D,MAAM,WAAW;IACjB,2CAA2C;IAC3C,cAAc,mBAAmB;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,mDAAmD;QACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C;0EACsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;mBACe;IACf,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C;;;OAGG;gBACS,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI7C;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;aAQvB,QAAQ,EAAE,MAAM;aAChB,UAAU,CAAC,EAAE,MAAM;IARrC;;;;OAIG;gBAED,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,YAAA;CAKtC"}

package/dist/translator/types.js

@@ -0,0 +1,58 @@
+/**
+ * Type definitions for the translator provider system.
+ *
+ * This module defines the provider enumeration, configuration schemas,
+ * result types, and typed error classes used by the translator adapters
+ * defined in {@link ./provider.ts}.
+ *
+ * @module translator/types
+ */
+/**
+ * Supported translation provider backends.
+ *
+ * Each enum member corresponds to a concrete adapter implementation in
+ * {@link ../translator/provider.ts}.
+ */
+export var TranslatorProviderType;
+(function (TranslatorProviderType) {
+    /** DeepL translation API (api-free.deepl.com or api.deepl.com). */
+    TranslatorProviderType["DeepL"] = "deepL";
+    /** OpenAI-compatible chat completion API for translation. */
+    TranslatorProviderType["OpenAI"] = "openAI";
+    /** Self-hosted LibreTranslate instance. */
+    TranslatorProviderType["LibreTranslate"] = "libreTranslate";
+})(TranslatorProviderType || (TranslatorProviderType = {}));
+/**
+ * Error thrown when a translator provider was selected but not configured
+ * with the required credentials.
+ */
+export class ProviderNotConfigured extends Error {
+    /**
+     * @param provider - Human-readable provider name (e.g. `'DeepL'`).
+     * @param reason - Explanation of what configuration is missing.
+     */
+    constructor(provider, reason) {
+        super(`Translator provider "${provider}" is not configured: ${reason}`);
+        this.name = 'ProviderNotConfigured';
+    }
+}
+/**
+ * Error thrown when a translation request fails at the network or provider
+ * level (timeout, non-2xx response, malformed reply, etc.).
+ */
+export class TranslationError extends Error {
+    provider;
+    statusCode;
+    /**
+     * @param message - Human-readable error description.
+     * @param provider - Name of the provider that produced the error.
+     * @param statusCode - HTTP status code from the provider, if applicable.
+     */
+    constructor(message, provider, statusCode) {
+        super(message);
+        this.provider = provider;
+        this.statusCode = statusCode;
+        this.name = 'TranslationError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/translator/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/translator/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,CAAN,IAAY,sBAOX;AAPD,WAAY,sBAAsB;IAChC,mEAAmE;IACnE,yCAAe,CAAA;IACf,6DAA6D;IAC7D,2CAAiB,CAAA;IACjB,2CAA2C;IAC3C,2DAAiC,CAAA;AACnC,CAAC,EAPW,sBAAsB,KAAtB,sBAAsB,QAOjC;AAsCD;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C;;;OAGG;IACH,YAAY,QAAgB,EAAE,MAAc;QAC1C,KAAK,CAAC,wBAAwB,QAAQ,wBAAwB,MAAM,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAQvB;IACA;IARlB;;;;OAIG;IACH,YACE,OAAe,EACC,QAAgB,EAChB,UAAmB;QAEnC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,aAAQ,GAAR,QAAQ,CAAQ;QAChB,eAAU,GAAV,UAAU,CAAS;QAGnC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}