@better-i18n/mcp-types 0.3.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-i18n/mcp-types",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Type definitions and schemas for Better i18n MCP API",
   "type": "module",
   "main": "./src/index.ts",

package/src/client-types.ts

@@ -16,6 +16,8 @@ import type {
   AddLanguageInput,
   GetSyncsInput,
   GetSyncInput,
+  GetPendingChangesInput,
+  PublishInput,
 } from "./schemas";
 
 import type {
@@ -29,6 +31,8 @@ import type {
   AddLanguageResponse,
   GetSyncsResponse,
   GetSyncResponse,
+  GetPendingChangesResponse,
+  PublishResponse,
 } from "./types";
 
 /**
@@ -70,6 +74,14 @@ export interface MCPClient {
   getSync: {
     query: (input: GetSyncInput) => Promise<GetSyncResponse>;
   };
+  getPendingChanges: {
+    query: (
+      input: GetPendingChangesInput,
+    ) => Promise<GetPendingChangesResponse>;
+  };
+  publish: {
+    mutate: (input: PublishInput) => Promise<PublishResponse>;
+  };
 }
 
 /**

package/src/schemas.ts

@@ -124,6 +124,39 @@ export type GetAllTranslationsInput = z.input<typeof getAllTranslationsInput>;
 // Write Endpoint Schemas - COMPACT FORMAT
 // ============================================================================
 
+/**
+ * Namespace context object for enriching namespace metadata.
+ * Provide this on any key to set context on its namespace.
+ * If multiple keys share a namespace, the last context wins.
+ */
+const namespaceContextSchema = z.object({
+  /** Human-readable description of the namespace */
+  description: z
+    .string()
+    .optional()
+    .describe("What this namespace contains (e.g., 'Authentication flow strings')"),
+  /** Owning team */
+  team: z
+    .string()
+    .optional()
+    .describe("Team responsible (e.g., 'auth-team')"),
+  /** Business domain */
+  domain: z
+    .string()
+    .optional()
+    .describe("Business domain (e.g., 'authentication', 'payments')"),
+  /** AI translation guidance specific to this namespace */
+  aiPrompt: z
+    .string()
+    .optional()
+    .describe("Extra AI translation instructions for this namespace"),
+  /** Organizational tags */
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe("Tags for categorization (e.g., ['critical', 'user-facing'])"),
+});
+
 /**
  * Compact key item for createKeys endpoint.
  *
@@ -132,6 +165,7 @@ export type GetAllTranslationsInput = z.input<typeof getAllTranslationsInput>;
  * - ns: namespace (default: "default")
  * - v: source value (source language text)
  * - t: translations object { langCode: text }
+ * - nc: namespace context (optional, enriches the namespace)
  */
 const compactCreateKeyItem = z.object({
   /** Key name (e.g., "submit_button", "nav.home") */
@@ -145,6 +179,12 @@ const compactCreateKeyItem = z.object({
     .record(z.string(), z.string())
     .optional()
     .describe("Target translations object"),
+  /** Namespace context - enriches the namespace with metadata */
+  nc: namespaceContextSchema
+    .optional()
+    .describe(
+      "Namespace context: description, team, domain, aiPrompt, tags. Sets metadata on the namespace.",
+    ),
 });
 
 /**
@@ -187,6 +227,12 @@ const compactUpdateItem = z.object({
   s: z.boolean().optional().describe("Is source language"),
   /** Status */
   st: z.string().optional().describe("Translation status"),
+  /** Namespace context - enriches the namespace with metadata */
+  nc: namespaceContextSchema
+    .optional()
+    .describe(
+      "Namespace context: description, team, domain, aiPrompt, tags. Sets metadata on the namespace.",
+    ),
 });
 
 /**
@@ -244,7 +290,7 @@ export const getSyncsInput = projectIdentifierSchema.extend({
     .describe("Filter syncs by status"),
   /** Filter by job type */
   type: z
-    .enum(["initial_import", "source_sync", "cdn_upload", "publish_batch"])
+    .enum(["initial_import", "source_sync", "cdn_upload", "batch_publish"])
     .optional()
     .describe("Filter syncs by job type"),
 });
@@ -260,3 +306,41 @@ export const getSyncInput = z.object({
   syncId: z.string().describe("The sync job ID to retrieve details for"),
 });
 export type GetSyncInput = z.input<typeof getSyncInput>;
+
+// ============================================================================
+// Publish Endpoint Schemas
+// ============================================================================
+
+/**
+ * Input schema for getPendingChanges endpoint.
+ * Returns what's ready to be published (translations, deleted keys, language changes).
+ */
+export const getPendingChangesInput = projectIdentifierSchema;
+export type GetPendingChangesInput = z.input<typeof getPendingChangesInput>;
+
+/**
+ * Input schema for publish endpoint.
+ * Publishes pending changes to CDN or GitHub.
+ *
+ * If translations array is omitted, ALL pending changes are published.
+ * If translations array is provided, only those specific translations are published.
+ */
+export const publishInput = projectIdentifierSchema.extend({
+  /**
+   * Optional: specific translations to publish.
+   * If omitted, all pending changes (translations + deleted keys + language changes) are published.
+   */
+  translations: z
+    .array(
+      z.object({
+        keyId: z.string().uuid(),
+        languageCode: z.string(),
+      }),
+    )
+    .optional()
+    .describe(
+      "Specific translations to publish. If omitted, all pending changes are published.",
+    ),
+});
+export type PublishOutput = z.infer<typeof publishInput>;
+export type PublishInput = z.input<typeof publishInput>;

package/src/types.ts

@@ -42,6 +42,25 @@ export interface LanguageCoverage {
   percentage: number;
 }
 
+/**
+ * Namespace metadata returned from read endpoints.
+ */
+export interface NamespaceInfo {
+  /** Namespace name ("default" for root keys) */
+  name: string;
+  /** Number of keys in this namespace */
+  keyCount: number;
+  /** Human-readable description */
+  description: string | null;
+  /** Structured context (team, domain, aiPrompt, tags) */
+  context: {
+    team?: string;
+    domain?: string;
+    aiPrompt?: string;
+    tags?: string[];
+  } | null;
+}
+
 /**
  * Response from getProject endpoint.
  */
@@ -50,8 +69,8 @@ export interface GetProjectResponse {
   project: string;
   /** Source language code */
   sourceLanguage: string;
-  /** Available namespaces */
-  namespaces: string[];
+  /** Available namespaces with metadata */
+  namespaces: NamespaceInfo[];
   /** Available target languages */
   languages: string[];
   /** Total number of translation keys */
@@ -112,6 +131,8 @@ export interface GetAllTranslationsResponse {
   status?: string;
   /** Translation keys with their translations */
   keys: KeyWithFullTranslations[];
+  /** Namespace metadata for namespaces present in results */
+  namespaceDetails?: Record<string, NamespaceInfo>;
 }
 
 /**
@@ -140,6 +161,8 @@ export interface ListKeysResponse {
   page: number;
   limit: number;
   keys: KeyWithTranslations[];
+  /** Namespace metadata for namespaces present in results */
+  namespaceDetails?: Record<string, NamespaceInfo>;
 }
 
 // ============================================================================
@@ -164,12 +187,20 @@ export interface CreateKeyResultItem {
 export interface CreateKeysResponse {
   /** Operation success */
   success: boolean;
-  /** Number of keys created */
+  /** Total keys created */
   keysCreated: number;
+  /** Number of new keys inserted */
+  created: number;
+  /** Number of soft-deleted keys renamed to free up key names */
+  renamed: number;
+  /** Number of duplicate keys skipped */
+  duplicates: number;
   /** Created key details */
   keys: CreateKeyResultItem[];
   /** Skipped keys (duplicates) */
   skipped?: Array<{ key: string; reason: string }>;
+  /** Pending publish hint - reminds AI to call publish */
+  pendingPublish?: PendingPublishHint;
 }
 
 /**
@@ -194,6 +225,8 @@ export interface UpdateKeysResponse {
   keysUpdated: number;
   /** Updated key details */
   updates: UpdateKeyResultItem[];
+  /** Pending publish hint - reminds AI to call publish */
+  pendingPublish?: PendingPublishHint;
 }
 
 /**
@@ -245,7 +278,7 @@ export type SyncJobType =
   | "initial_import"
   | "source_sync"
   | "cdn_upload"
-  | "publish_batch";
+  | "batch_publish";
 
 /**
  * Sync job status.
@@ -321,3 +354,109 @@ export interface GetSyncResponse {
   /** Affected keys */
   affectedKeys: AffectedKey[];
 }
+
+// ============================================================================
+// Publish Types
+// ============================================================================
+
+/**
+ * Preview item for pending translation.
+ */
+export interface PendingTranslationPreview {
+  /** Key UUID */
+  keyId: string;
+  /** Key name */
+  key: string;
+  /** Namespace */
+  namespace: string | null;
+  /** Translation text */
+  text: string;
+  /** Translation status */
+  status: string;
+}
+
+/**
+ * Pending changes by language.
+ */
+export interface PendingChangesByLanguage {
+  /** Number of pending translations */
+  count: number;
+  /** Preview of first few translations */
+  preview: PendingTranslationPreview[];
+}
+
+/**
+ * Deleted key info.
+ */
+export interface PendingDeletedKey {
+  /** Key UUID */
+  keyId: string;
+  /** Key name */
+  key: string;
+  /** Namespace */
+  namespace: string | null;
+  /** Source text */
+  sourceText: string | null;
+}
+
+/**
+ * Response from getPendingChanges endpoint.
+ */
+export interface GetPendingChangesResponse {
+  /** Project identifier */
+  project: string;
+  /** Whether there are any pending changes */
+  hasPendingChanges: boolean;
+  /** Summary counts */
+  summary: {
+    /** Total pending translations */
+    translations: number;
+    /** Keys marked for deletion */
+    deletedKeys: number;
+    /** Language status changes */
+    languageChanges: number;
+    /** Total changes */
+    total: number;
+  };
+  /** Breakdown by language code */
+  byLanguage: Record<string, PendingChangesByLanguage>;
+  /** Deleted keys awaiting publish */
+  deletedKeys: PendingDeletedKey[];
+  /** Publish destination */
+  publishDestination: "github" | "cdn" | "none";
+  /** Reason if cannot publish */
+  cannotPublishReason?: string;
+}
+
+/**
+ * Response from publish endpoint.
+ */
+export interface PublishResponse {
+  /** Operation success */
+  success: boolean;
+  /** Number of translations published */
+  published: number;
+  /** Number of repositories updated */
+  repositories: number;
+  /** Created sync job IDs */
+  syncJobIds: string[];
+  /** Number of deleted keys processed */
+  deletedKeysProcessed?: number;
+  /** Number of language changes processed */
+  languageChangesProcessed?: number;
+  /** Human-readable message */
+  message: string;
+}
+
+/**
+ * Pending publish hint included in write operation responses.
+ * Helps AI model know when to call publish.
+ */
+export interface PendingPublishHint {
+  /** Whether there are unpublished changes */
+  hasChanges: boolean;
+  /** Number of pending changes from this operation */
+  count: number;
+  /** Hint message for AI */
+  hint: string;
+}