@kb-labs/inbox-entry 2.96.0

package/README.md

@@ -0,0 +1,5 @@
+# @kb-labs/inbox-entry
+
+> Part of [KB Labs](https://github.com/KirillBaranov/kb-labs) ecosystem.
+
+V3 plugin manifest, CLI commands, and REST handlers for the inbox plugin.

package/dist/commands/mail-accounts.d.ts

@@ -0,0 +1,10 @@
+import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+import * as _kb_labs_inbox_contracts from '@kb-labs/inbox-contracts';
+import { CLIInput } from '@kb-labs/sdk';
+
+type AccountsFlags = {
+    json?: boolean;
+};
+declare const _default: _kb_labs_shared_command_kit.CommandHandlerV3<unknown, CLIInput<AccountsFlags>, _kb_labs_inbox_contracts.AccountInfo[] | null>;
+
+export { _default as default };

package/dist/commands/mail-accounts.js

@@ -0,0 +1,104 @@
+import { defineCommand } from '@kb-labs/sdk';
+import { listAccounts, InboxError } from '@kb-labs/inbox-core';
+
+// src/commands/mail-accounts.ts
+function getHint(code, message) {
+  switch (code) {
+    case "ENV_MISSING":
+      return "Set INBOX_ACCOUNTS=work,personal and account vars (INBOX_ACCOUNT_WORK_USER, _PASS, _IMAP_HOST, _SMTP_HOST)";
+    case "ACCOUNT_NOT_FOUND":
+      return `Use kb inbox accounts to see configured accounts, then pass the name with --account`;
+    case "IMAP_AUTH_FAILED":
+      return "Create an app-password in Yandex ID settings (yandex.ru/id) and set it as INBOX_ACCOUNT_<NAME>_PASS";
+    case "IMAP_CONNECT_FAILED":
+      return `Check INBOX_ACCOUNT_<NAME>_IMAP_HOST and _IMAP_PORT, and that the server is reachable`;
+    case "IMAP_TIMEOUT":
+      return "Server did not respond in time \u2014 try again in a moment";
+    case "IMAP_MAILBOX_NOT_FOUND":
+      return "Run kb inbox folders --account <name> to see available folders";
+    case "MESSAGE_NOT_FOUND":
+      return "The uid may be stale \u2014 refresh with: kb inbox list";
+    case "SMTP_AUTH_FAILED":
+      return "Create an app-password in Yandex ID settings and set it as INBOX_ACCOUNT_<NAME>_PASS";
+    case "SMTP_CONNECT_FAILED":
+      return "Check INBOX_ACCOUNT_<NAME>_SMTP_HOST and _SMTP_PORT";
+    case "SMTP_INVALID_RECIPIENT":
+      return "Verify the --to address is a valid email";
+    case "VALIDATION_ERROR":
+      return void 0;
+    // message itself is descriptive enough
+    case "INTERNAL_ERROR":
+      return void 0;
+    default: {
+      return void 0;
+    }
+  }
+}
+function handleError(ctx, err, isJson) {
+  if (err instanceof InboxError) {
+    const hint = getHint(err.code, err.message);
+    if (isJson) {
+      ctx.ui?.json?.({
+        ok: false,
+        error: {
+          code: err.code,
+          message: err.message,
+          ...hint && { hint }
+        }
+      });
+    } else {
+      ctx.ui?.error?.(err.message, {
+        ...hint && { hint },
+        cause: `InboxError [${err.code}]`
+      });
+    }
+    return;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  if (isJson) {
+    ctx.ui?.json?.({
+      ok: false,
+      error: { code: "INTERNAL_ERROR", message }
+    });
+  } else {
+    ctx.ui?.error?.(message);
+  }
+}
+
+// src/commands/mail-accounts.ts
+var mail_accounts_default = defineCommand({
+  id: "inbox:accounts",
+  description: "List configured email accounts",
+  handler: {
+    async execute(ctx, input) {
+      try {
+        const accounts = listAccounts();
+        if (input.flags.json) {
+          ctx.ui?.json?.({ ok: true, result: accounts });
+          return { exitCode: 0, result: accounts };
+        }
+        if (!accounts.length) {
+          ctx.ui?.info?.("No accounts configured. Set INBOX_ACCOUNTS=work,personal and account vars.");
+          return { exitCode: 0, result: accounts };
+        }
+        ctx.ui?.chain?.(accounts.map((acc, i) => ({
+          title: `[${i}] ${acc.name}`,
+          sections: [{
+            items: [
+              `user: ${acc.user}`,
+              `imap: ${acc.imapHost}:${acc.imapPort}`
+            ]
+          }]
+        })));
+        return { exitCode: 0, result: accounts };
+      } catch (err) {
+        handleError(ctx, err, input.flags.json);
+        return { exitCode: 1, result: null };
+      }
+    }
+  }
+});
+
+export { mail_accounts_default as default };
+//# sourceMappingURL=mail-accounts.js.map
+//# sourceMappingURL=mail-accounts.js.map

package/dist/commands/mail-accounts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/error.ts","../../src/commands/mail-accounts.ts"],"names":[],"mappings":"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","file":"mail-accounts.js","sourcesContent":["import type { PluginContextV3 } from '@kb-labs/sdk';\nimport { InboxError, type InboxErrorCode } from '@kb-labs/inbox-core';\n\n// HTTP status codes for REST layer\nconst REST_STATUS: Record<InboxErrorCode, number> = {\n  ENV_MISSING:            400,\n  ACCOUNT_NOT_FOUND:      400,\n  IMAP_AUTH_FAILED:       401,\n  IMAP_CONNECT_FAILED:    503,\n  IMAP_TIMEOUT:           504,\n  IMAP_MAILBOX_NOT_FOUND: 404,\n  MESSAGE_NOT_FOUND:      404,\n  SMTP_AUTH_FAILED:       401,\n  SMTP_CONNECT_FAILED:    503,\n  SMTP_INVALID_RECIPIENT: 400,\n  VALIDATION_ERROR:       400,\n  INTERNAL_ERROR:         500,\n};\n\n// Human-readable hints per error code\nfunction getHint(code: InboxErrorCode, message: string): string | undefined {\n  switch (code) {\n    case 'ENV_MISSING':\n      return 'Set INBOX_ACCOUNTS=work,personal and account vars (INBOX_ACCOUNT_WORK_USER, _PASS, _IMAP_HOST, _SMTP_HOST)';\n    case 'ACCOUNT_NOT_FOUND':\n      return `Use kb inbox accounts to see configured accounts, then pass the name with --account`;\n    case 'IMAP_AUTH_FAILED':\n      return 'Create an app-password in Yandex ID settings (yandex.ru/id) and set it as INBOX_ACCOUNT_<NAME>_PASS';\n    case 'IMAP_CONNECT_FAILED':\n      return `Check INBOX_ACCOUNT_<NAME>_IMAP_HOST and _IMAP_PORT, and that the server is reachable`;\n    case 'IMAP_TIMEOUT':\n      return 'Server did not respond in time — try again in a moment';\n    case 'IMAP_MAILBOX_NOT_FOUND':\n      return 'Run kb inbox folders --account <name> to see available folders';\n    case 'MESSAGE_NOT_FOUND':\n      return 'The uid may be stale — refresh with: kb inbox list';\n    case 'SMTP_AUTH_FAILED':\n      return 'Create an app-password in Yandex ID settings and set it as INBOX_ACCOUNT_<NAME>_PASS';\n    case 'SMTP_CONNECT_FAILED':\n      return 'Check INBOX_ACCOUNT_<NAME>_SMTP_HOST and _SMTP_PORT';\n    case 'SMTP_INVALID_RECIPIENT':\n      return 'Verify the --to address is a valid email';\n    case 'VALIDATION_ERROR':\n      return undefined; // message itself is descriptive enough\n    case 'INTERNAL_ERROR':\n      return undefined;\n    default: {\n      const _: never = code;\n      void _;\n      return undefined;\n    }\n  }\n}\n\n/**\n * Output a structured error for CLI commands.\n *\n * JSON mode  → { ok: false, error: { code, message, hint? } }  — agent-parseable\n * Human mode → ctx.ui.error() with hint and cause fields\n *\n * Call right before `return { exitCode: 1, result: null }`.\n */\nexport function handleError(ctx: PluginContextV3, err: unknown, isJson?: boolean): void {\n  if (err instanceof InboxError) {\n    const hint = getHint(err.code, err.message);\n\n    if (isJson) {\n      ctx.ui?.json?.({\n        ok: false,\n        error: {\n          code: err.code,\n          message: err.message,\n          ...(hint && { hint }),\n        },\n      });\n    } else {\n      ctx.ui?.error?.(err.message, {\n        ...(hint && { hint }),\n        cause: `InboxError [${err.code}]`,\n      });\n    }\n    return;\n  }\n\n  // Unknown error\n  const message = err instanceof Error ? err.message : String(err);\n\n  if (isJson) {\n    ctx.ui?.json?.({\n      ok: false,\n      error: { code: 'INTERNAL_ERROR', message },\n    });\n  } else {\n    ctx.ui?.error?.(message);\n  }\n}\n\n/**\n * Re-throws err as an HTTP-aware error for REST handlers.\n * InboxError → preserves HTTP status; others → 500.\n */\nexport function rethrowForRest(err: unknown): never {\n  if (err instanceof InboxError) {\n    const hint = getHint(err.code, err.message);\n    throw Object.assign(new Error(err.message), {\n      statusCode: REST_STATUS[err.code] ?? 500,\n      code: err.code,\n      details: hint ? { hint } : undefined,\n    });\n  }\n\n  const message = err instanceof Error ? err.message : String(err);\n  throw Object.assign(new Error(message), {\n    statusCode: 500,\n    code: 'INTERNAL_ERROR',\n  });\n}\n","import { defineCommand, type CLIInput, type PluginContextV3 } from '@kb-labs/sdk';\nimport { listAccounts } from '@kb-labs/inbox-core';\nimport { handleError } from '../utils/error.js';\n\ntype AccountsFlags = {\n  json?: boolean;\n};\n\nexport default defineCommand({\n  id: 'inbox:accounts',\n  description: 'List configured email accounts',\n\n  handler: {\n    async execute(ctx: PluginContextV3, input: CLIInput<AccountsFlags>) {\n      try {\n        const accounts = listAccounts();\n\n        if (input.flags.json) {\n          ctx.ui?.json?.({ ok: true, result: accounts });\n          return { exitCode: 0, result: accounts };\n        }\n\n        if (!accounts.length) {\n          ctx.ui?.info?.('No accounts configured. Set INBOX_ACCOUNTS=work,personal and account vars.');\n          return { exitCode: 0, result: accounts };\n        }\n\n        ctx.ui?.chain?.(accounts.map((acc, i) => ({\n          title: `[${i}] ${acc.name}`,\n          sections: [{\n            items: [\n              `user: ${acc.user}`,\n              `imap: ${acc.imapHost}:${acc.imapPort}`,\n            ],\n          }],\n        })));\n\n        return { exitCode: 0, result: accounts };\n      } catch (err) {\n        handleError(ctx, err, input.flags.json);\n        return { exitCode: 1, result: null };\n      }\n    },\n  },\n});\n"]}

package/dist/commands/mail-delete.d.ts

@@ -0,0 +1,14 @@
+import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+import { CLIInput } from '@kb-labs/sdk';
+
+type DeleteFlags = {
+    folder?: string;
+    account?: string;
+    json?: boolean;
+};
+declare const _default: _kb_labs_shared_command_kit.CommandHandlerV3<unknown, CLIInput<DeleteFlags>, {
+    uid: number;
+    deleted: boolean;
+} | null>;
+
+export { _default as default };

package/dist/commands/mail-delete.js

@@ -0,0 +1,103 @@
+import { defineCommand, validationError } from '@kb-labs/sdk';
+import { resolveAccount, deleteMessage, InboxError } from '@kb-labs/inbox-core';
+
+// src/commands/mail-delete.ts
+function getHint(code, message) {
+  switch (code) {
+    case "ENV_MISSING":
+      return "Set INBOX_ACCOUNTS=work,personal and account vars (INBOX_ACCOUNT_WORK_USER, _PASS, _IMAP_HOST, _SMTP_HOST)";
+    case "ACCOUNT_NOT_FOUND":
+      return `Use kb inbox accounts to see configured accounts, then pass the name with --account`;
+    case "IMAP_AUTH_FAILED":
+      return "Create an app-password in Yandex ID settings (yandex.ru/id) and set it as INBOX_ACCOUNT_<NAME>_PASS";
+    case "IMAP_CONNECT_FAILED":
+      return `Check INBOX_ACCOUNT_<NAME>_IMAP_HOST and _IMAP_PORT, and that the server is reachable`;
+    case "IMAP_TIMEOUT":
+      return "Server did not respond in time \u2014 try again in a moment";
+    case "IMAP_MAILBOX_NOT_FOUND":
+      return "Run kb inbox folders --account <name> to see available folders";
+    case "MESSAGE_NOT_FOUND":
+      return "The uid may be stale \u2014 refresh with: kb inbox list";
+    case "SMTP_AUTH_FAILED":
+      return "Create an app-password in Yandex ID settings and set it as INBOX_ACCOUNT_<NAME>_PASS";
+    case "SMTP_CONNECT_FAILED":
+      return "Check INBOX_ACCOUNT_<NAME>_SMTP_HOST and _SMTP_PORT";
+    case "SMTP_INVALID_RECIPIENT":
+      return "Verify the --to address is a valid email";
+    case "VALIDATION_ERROR":
+      return void 0;
+    // message itself is descriptive enough
+    case "INTERNAL_ERROR":
+      return void 0;
+    default: {
+      return void 0;
+    }
+  }
+}
+function handleError(ctx, err, isJson) {
+  if (err instanceof InboxError) {
+    const hint = getHint(err.code, err.message);
+    if (isJson) {
+      ctx.ui?.json?.({
+        ok: false,
+        error: {
+          code: err.code,
+          message: err.message,
+          ...hint && { hint }
+        }
+      });
+    } else {
+      ctx.ui?.error?.(err.message, {
+        ...hint && { hint },
+        cause: `InboxError [${err.code}]`
+      });
+    }
+    return;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  if (isJson) {
+    ctx.ui?.json?.({
+      ok: false,
+      error: { code: "INTERNAL_ERROR", message }
+    });
+  } else {
+    ctx.ui?.error?.(message);
+  }
+}
+
+// src/commands/mail-delete.ts
+var mail_delete_default = defineCommand({
+  id: "inbox:mail.delete",
+  description: "Delete an email (moves to Trash)",
+  handler: {
+    async execute(ctx, input) {
+      const [rawUid] = input.argv;
+      if (!rawUid) {
+        validationError(ctx, "uid is required", "Usage: kb inbox delete <uid>", input.flags.json);
+        return { exitCode: 1, result: null };
+      }
+      const uid = parseInt(rawUid, 10);
+      if (isNaN(uid)) {
+        validationError(ctx, `Invalid uid: "${rawUid}" \u2014 must be a number`, void 0, input.flags.json);
+        return { exitCode: 1, result: null };
+      }
+      try {
+        const account = resolveAccount(input.flags.account);
+        await deleteMessage(account, uid, input.flags.folder ?? "INBOX");
+        if (input.flags.json) {
+          ctx.ui?.json?.({ ok: true, result: { uid, deleted: true } });
+          return { exitCode: 0, result: { uid, deleted: true } };
+        }
+        ctx.ui?.success?.(`Deleted uid=${uid}`);
+        return { exitCode: 0, result: null };
+      } catch (err) {
+        handleError(ctx, err, input.flags.json);
+        return { exitCode: 1, result: null };
+      }
+    }
+  }
+});
+
+export { mail_delete_default as default };
+//# sourceMappingURL=mail-delete.js.map
+//# sourceMappingURL=mail-delete.js.map

package/dist/commands/mail-delete.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/error.ts","../../src/commands/mail-delete.ts"],"names":[],"mappings":";;;;AAoBA,SAAS,OAAA,CAAQ,MAAsB,OAAA,EAAqC;AAC1E,EAAA,QAAQ,IAAA;AAAM,IACZ,KAAK,aAAA;AACH,MAAA,OAAO,4GAAA;AAAA,IACT,KAAK,mBAAA;AACH,MAAA,OAAO,CAAA,mFAAA,CAAA;AAAA,IACT,KAAK,kBAAA;AACH,MAAA,OAAO,qGAAA;AAAA,IACT,KAAK,qBAAA;AACH,MAAA,OAAO,CAAA,qFAAA,CAAA;AAAA,IACT,KAAK,cAAA;AACH,MAAA,OAAO,6DAAA;AAAA,IACT,KAAK,wBAAA;AACH,MAAA,OAAO,gEAAA;AAAA,IACT,KAAK,mBAAA;AACH,MAAA,OAAO,yDAAA;AAAA,IACT,KAAK,kBAAA;AACH,MAAA,OAAO,sFAAA;AAAA,IACT,KAAK,qBAAA;AACH,MAAA,OAAO,qDAAA;AAAA,IACT,KAAK,wBAAA;AACH,MAAA,OAAO,0CAAA;AAAA,IACT,KAAK,kBAAA;AACH,MAAA,OAAO,MAAA;AAAA;AAAA,IACT,KAAK,gBAAA;AACH,MAAA,OAAO,MAAA;AAAA,IACT,SAAS;AAGP,MAAA,OAAO,MAAA;AAAA,IACT;AAAA;AAEJ;AAUO,SAAS,WAAA,CAAY,GAAA,EAAsB,GAAA,EAAc,MAAA,EAAwB;AACtF,EAAA,IAAI,eAAe,UAAA,EAAY;AAC7B,IAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,GAAA,CAAI,IAAA,EAAM,IAAI,OAAO,CAAA;AAE1C,IAAA,IAAI,MAAA,EAAQ;AACV,MAAA,GAAA,CAAI,IAAI,IAAA,GAAO;AAAA,QACb,EAAA,EAAI,KAAA;AAAA,QACJ,KAAA,EAAO;AAAA,UACL,MAAM,GAAA,CAAI,IAAA;AAAA,UACV,SAAS,GAAA,CAAI,OAAA;AAAA,UACb,GAAI,IAAA,IAAQ,EAAE,IAAA;AAAK;AACrB,OACD,CAAA;AAAA,IACH,CAAA,MAAO;AACL,MAAA,GAAA,CAAI,EAAA,EAAI,KAAA,GAAQ,GAAA,CAAI,OAAA,EAAS;AAAA,QAC3B,GAAI,IAAA,IAAQ,EAAE,IAAA,EAAK;AAAA,QACnB,KAAA,EAAO,CAAA,YAAA,EAAe,GAAA,CAAI,IAAI,CAAA,CAAA;AAAA,OAC/B,CAAA;AAAA,IACH;AACA,IAAA;AAAA,EACF;AAGA,EAAA,MAAM,UAAU,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU,OAAO,GAAG,CAAA;AAE/D,EAAA,IAAI,MAAA,EAAQ;AACV,IAAA,GAAA,CAAI,IAAI,IAAA,GAAO;AAAA,MACb,EAAA,EAAI,KAAA;AAAA,MACJ,KAAA,EAAO,EAAE,IAAA,EAAM,gBAAA,EAAkB,OAAA;AAAQ,KAC1C,CAAA;AAAA,EACH,CAAA,MAAO;AACL,IAAA,GAAA,CAAI,EAAA,EAAI,QAAQ,OAAO,CAAA;AAAA,EACzB;AACF;;;ACrFA,IAAO,sBAAQ,aAAA,CAAc;AAAA,EAC3B,EAAA,EAAI,mBAAA;AAAA,EACJ,WAAA,EAAa,kCAAA;AAAA,EAEb,OAAA,EAAS;AAAA,IACP,MAAM,OAAA,CAAQ,GAAA,EAAsB,KAAA,EAA8B;AAChE,MAAA,MAAM,CAAC,MAAM,CAAA,GAAI,KAAA,CAAM,IAAA;AACvB,MAAA,IAAI,CAAC,MAAA,EAAQ;AACX,QAAA,eAAA,CAAgB,GAAA,EAAK,iBAAA,EAAmB,8BAAA,EAAgC,KAAA,CAAM,MAAM,IAAI,CAAA;AACxF,QAAA,OAAO,EAAE,QAAA,EAAU,CAAA,EAAG,MAAA,EAAQ,IAAA,EAAK;AAAA,MACrC;AAEA,MAAA,MAAM,GAAA,GAAM,QAAA,CAAS,MAAA,EAAQ,EAAE,CAAA;AAC/B,MAAA,IAAI,KAAA,CAAM,GAAG,CAAA,EAAG;AACd,QAAA,eAAA,CAAgB,KAAK,CAAA,cAAA,EAAiB,MAAM,6BAAwB,MAAA,EAAW,KAAA,CAAM,MAAM,IAAI,CAAA;AAC/F,QAAA,OAAO,EAAE,QAAA,EAAU,CAAA,EAAG,MAAA,EAAQ,IAAA,EAAK;AAAA,MACrC;AAEA,MAAA,IAAI;AACF,QAAA,MAAM,OAAA,GAAU,cAAA,CAAe,KAAA,CAAM,KAAA,CAAM,OAAO,CAAA;AAClD,QAAA,MAAM,cAAc,OAAA,EAAS,GAAA,EAAK,KAAA,CAAM,KAAA,CAAM,UAAU,OAAO,CAAA;AAE/D,QAAA,IAAI,KAAA,CAAM,MAAM,IAAA,EAAM;AACpB,UAAA,GAAA,CAAI,EAAA,EAAI,IAAA,GAAO,EAAE,EAAA,EAAI,IAAA,EAAM,MAAA,EAAQ,EAAE,GAAA,EAAK,OAAA,EAAS,IAAA,EAAK,EAAG,CAAA;AAC3D,UAAA,OAAO,EAAE,UAAU,CAAA,EAAG,MAAA,EAAQ,EAAE,GAAA,EAAK,OAAA,EAAS,MAAK,EAAE;AAAA,QACvD;AAEA,QAAA,GAAA,CAAI,EAAA,EAAI,OAAA,GAAU,CAAA,YAAA,EAAe,GAAG,CAAA,CAAE,CAAA;AACtC,QAAA,OAAO,EAAE,QAAA,EAAU,CAAA,EAAG,MAAA,EAAQ,IAAA,EAAK;AAAA,MACrC,SAAS,GAAA,EAAK;AACZ,QAAA,WAAA,CAAY,GAAA,EAAK,GAAA,EAAK,KAAA,CAAM,KAAA,CAAM,IAAI,CAAA;AACtC,QAAA,OAAO,EAAE,QAAA,EAAU,CAAA,EAAG,MAAA,EAAQ,IAAA,EAAK;AAAA,MACrC;AAAA,IACF;AAAA;AAEJ,CAAC","file":"mail-delete.js","sourcesContent":["import type { PluginContextV3 } from '@kb-labs/sdk';\nimport { InboxError, type InboxErrorCode } from '@kb-labs/inbox-core';\n\n// HTTP status codes for REST layer\nconst REST_STATUS: Record<InboxErrorCode, number> = {\n  ENV_MISSING:            400,\n  ACCOUNT_NOT_FOUND:      400,\n  IMAP_AUTH_FAILED:       401,\n  IMAP_CONNECT_FAILED:    503,\n  IMAP_TIMEOUT:           504,\n  IMAP_MAILBOX_NOT_FOUND: 404,\n  MESSAGE_NOT_FOUND:      404,\n  SMTP_AUTH_FAILED:       401,\n  SMTP_CONNECT_FAILED:    503,\n  SMTP_INVALID_RECIPIENT: 400,\n  VALIDATION_ERROR:       400,\n  INTERNAL_ERROR:         500,\n};\n\n// Human-readable hints per error code\nfunction getHint(code: InboxErrorCode, message: string): string | undefined {\n  switch (code) {\n    case 'ENV_MISSING':\n      return 'Set INBOX_ACCOUNTS=work,personal and account vars (INBOX_ACCOUNT_WORK_USER, _PASS, _IMAP_HOST, _SMTP_HOST)';\n    case 'ACCOUNT_NOT_FOUND':\n      return `Use kb inbox accounts to see configured accounts, then pass the name with --account`;\n    case 'IMAP_AUTH_FAILED':\n      return 'Create an app-password in Yandex ID settings (yandex.ru/id) and set it as INBOX_ACCOUNT_<NAME>_PASS';\n    case 'IMAP_CONNECT_FAILED':\n      return `Check INBOX_ACCOUNT_<NAME>_IMAP_HOST and _IMAP_PORT, and that the server is reachable`;\n    case 'IMAP_TIMEOUT':\n      return 'Server did not respond in time — try again in a moment';\n    case 'IMAP_MAILBOX_NOT_FOUND':\n      return 'Run kb inbox folders --account <name> to see available folders';\n    case 'MESSAGE_NOT_FOUND':\n      return 'The uid may be stale — refresh with: kb inbox list';\n    case 'SMTP_AUTH_FAILED':\n      return 'Create an app-password in Yandex ID settings and set it as INBOX_ACCOUNT_<NAME>_PASS';\n    case 'SMTP_CONNECT_FAILED':\n      return 'Check INBOX_ACCOUNT_<NAME>_SMTP_HOST and _SMTP_PORT';\n    case 'SMTP_INVALID_RECIPIENT':\n      return 'Verify the --to address is a valid email';\n    case 'VALIDATION_ERROR':\n      return undefined; // message itself is descriptive enough\n    case 'INTERNAL_ERROR':\n      return undefined;\n    default: {\n      const _: never = code;\n      void _;\n      return undefined;\n    }\n  }\n}\n\n/**\n * Output a structured error for CLI commands.\n *\n * JSON mode  → { ok: false, error: { code, message, hint? } }  — agent-parseable\n * Human mode → ctx.ui.error() with hint and cause fields\n *\n * Call right before `return { exitCode: 1, result: null }`.\n */\nexport function handleError(ctx: PluginContextV3, err: unknown, isJson?: boolean): void {\n  if (err instanceof InboxError) {\n    const hint = getHint(err.code, err.message);\n\n    if (isJson) {\n      ctx.ui?.json?.({\n        ok: false,\n        error: {\n          code: err.code,\n          message: err.message,\n          ...(hint && { hint }),\n        },\n      });\n    } else {\n      ctx.ui?.error?.(err.message, {\n        ...(hint && { hint }),\n        cause: `InboxError [${err.code}]`,\n      });\n    }\n    return;\n  }\n\n  // Unknown error\n  const message = err instanceof Error ? err.message : String(err);\n\n  if (isJson) {\n    ctx.ui?.json?.({\n      ok: false,\n      error: { code: 'INTERNAL_ERROR', message },\n    });\n  } else {\n    ctx.ui?.error?.(message);\n  }\n}\n\n/**\n * Re-throws err as an HTTP-aware error for REST handlers.\n * InboxError → preserves HTTP status; others → 500.\n */\nexport function rethrowForRest(err: unknown): never {\n  if (err instanceof InboxError) {\n    const hint = getHint(err.code, err.message);\n    throw Object.assign(new Error(err.message), {\n      statusCode: REST_STATUS[err.code] ?? 500,\n      code: err.code,\n      details: hint ? { hint } : undefined,\n    });\n  }\n\n  const message = err instanceof Error ? err.message : String(err);\n  throw Object.assign(new Error(message), {\n    statusCode: 500,\n    code: 'INTERNAL_ERROR',\n  });\n}\n","import { defineCommand, validationError, type CLIInput, type PluginContextV3 } from '@kb-labs/sdk';\nimport { resolveAccount, deleteMessage } from '@kb-labs/inbox-core';\nimport { handleError } from '../utils/error.js';\n\ntype DeleteFlags = {\n  folder?: string;\n  account?: string;\n  json?: boolean;\n};\n\nexport default defineCommand({\n  id: 'inbox:mail.delete',\n  description: 'Delete an email (moves to Trash)',\n\n  handler: {\n    async execute(ctx: PluginContextV3, input: CLIInput<DeleteFlags>) {\n      const [rawUid] = input.argv;\n      if (!rawUid) {\n        validationError(ctx, 'uid is required', 'Usage: kb inbox delete <uid>', input.flags.json);\n        return { exitCode: 1, result: null };\n      }\n\n      const uid = parseInt(rawUid, 10);\n      if (isNaN(uid)) {\n        validationError(ctx, `Invalid uid: \"${rawUid}\" — must be a number`, undefined, input.flags.json);\n        return { exitCode: 1, result: null };\n      }\n\n      try {\n        const account = resolveAccount(input.flags.account);\n        await deleteMessage(account, uid, input.flags.folder ?? 'INBOX');\n\n        if (input.flags.json) {\n          ctx.ui?.json?.({ ok: true, result: { uid, deleted: true } });\n          return { exitCode: 0, result: { uid, deleted: true } };\n        }\n\n        ctx.ui?.success?.(`Deleted uid=${uid}`);\n        return { exitCode: 0, result: null };\n      } catch (err) {\n        handleError(ctx, err, input.flags.json);\n        return { exitCode: 1, result: null };\n      }\n    },\n  },\n});\n"]}

package/dist/commands/mail-folders.d.ts

@@ -0,0 +1,11 @@
+import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+import * as _kb_labs_inbox_contracts from '@kb-labs/inbox-contracts';
+import { CLIInput } from '@kb-labs/sdk';
+
+type FoldersFlags = {
+    account?: string;
+    json?: boolean;
+};
+declare const _default: _kb_labs_shared_command_kit.CommandHandlerV3<unknown, CLIInput<FoldersFlags>, _kb_labs_inbox_contracts.Folder[] | null>;
+
+export { _default as default };

package/dist/commands/mail-folders.js

@@ -0,0 +1,103 @@
+import { defineCommand } from '@kb-labs/sdk';
+import { resolveAccount, listFolders, InboxError } from '@kb-labs/inbox-core';
+
+// src/commands/mail-folders.ts
+function getHint(code, message) {
+  switch (code) {
+    case "ENV_MISSING":
+      return "Set INBOX_ACCOUNTS=work,personal and account vars (INBOX_ACCOUNT_WORK_USER, _PASS, _IMAP_HOST, _SMTP_HOST)";
+    case "ACCOUNT_NOT_FOUND":
+      return `Use kb inbox accounts to see configured accounts, then pass the name with --account`;
+    case "IMAP_AUTH_FAILED":
+      return "Create an app-password in Yandex ID settings (yandex.ru/id) and set it as INBOX_ACCOUNT_<NAME>_PASS";
+    case "IMAP_CONNECT_FAILED":
+      return `Check INBOX_ACCOUNT_<NAME>_IMAP_HOST and _IMAP_PORT, and that the server is reachable`;
+    case "IMAP_TIMEOUT":
+      return "Server did not respond in time \u2014 try again in a moment";
+    case "IMAP_MAILBOX_NOT_FOUND":
+      return "Run kb inbox folders --account <name> to see available folders";
+    case "MESSAGE_NOT_FOUND":
+      return "The uid may be stale \u2014 refresh with: kb inbox list";
+    case "SMTP_AUTH_FAILED":
+      return "Create an app-password in Yandex ID settings and set it as INBOX_ACCOUNT_<NAME>_PASS";
+    case "SMTP_CONNECT_FAILED":
+      return "Check INBOX_ACCOUNT_<NAME>_SMTP_HOST and _SMTP_PORT";
+    case "SMTP_INVALID_RECIPIENT":
+      return "Verify the --to address is a valid email";
+    case "VALIDATION_ERROR":
+      return void 0;
+    // message itself is descriptive enough
+    case "INTERNAL_ERROR":
+      return void 0;
+    default: {
+      return void 0;
+    }
+  }
+}
+function handleError(ctx, err, isJson) {
+  if (err instanceof InboxError) {
+    const hint = getHint(err.code, err.message);
+    if (isJson) {
+      ctx.ui?.json?.({
+        ok: false,
+        error: {
+          code: err.code,
+          message: err.message,
+          ...hint && { hint }
+        }
+      });
+    } else {
+      ctx.ui?.error?.(err.message, {
+        ...hint && { hint },
+        cause: `InboxError [${err.code}]`
+      });
+    }
+    return;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  if (isJson) {
+    ctx.ui?.json?.({
+      ok: false,
+      error: { code: "INTERNAL_ERROR", message }
+    });
+  } else {
+    ctx.ui?.error?.(message);
+  }
+}
+
+// src/commands/mail-folders.ts
+var mail_folders_default = defineCommand({
+  id: "inbox:folders",
+  description: "List available folders/mailboxes",
+  handler: {
+    async execute(ctx, input) {
+      try {
+        const account = resolveAccount(input.flags.account);
+        const folders = await listFolders(account);
+        if (input.flags.json) {
+          ctx.ui?.json?.({ ok: true, result: folders });
+          return { exitCode: 0, result: folders };
+        }
+        ctx.ui?.chain?.(folders.map((f) => ({
+          title: f.path,
+          sections: [{
+            items: [
+              [
+                f.specialUse ? `special: ${f.specialUse}` : null,
+                f.flags.length ? `flags: ${f.flags.join(" ")}` : null
+              ].filter(Boolean).join("  ") || "\u2014"
+            ]
+          }]
+        })));
+        return { exitCode: 0, result: folders };
+      } catch (err) {
+        handleError(ctx, err, input.flags.json);
+        return { exitCode: 1, result: null };
+      }
+    }
+  }
+});
+
+export { mail_folders_default as default };
+//# sourceMappingURL=mail-folders.js.map
+//# sourceMappingURL=mail-folders.js.map

package/dist/commands/mail-folders.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/error.ts","../../src/commands/mail-folders.ts"],"names":[],"mappings":"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","file":"mail-folders.js","sourcesContent":["import type { PluginContextV3 } from '@kb-labs/sdk';\nimport { InboxError, type InboxErrorCode } from '@kb-labs/inbox-core';\n\n// HTTP status codes for REST layer\nconst REST_STATUS: Record<InboxErrorCode, number> = {\n  ENV_MISSING:            400,\n  ACCOUNT_NOT_FOUND:      400,\n  IMAP_AUTH_FAILED:       401,\n  IMAP_CONNECT_FAILED:    503,\n  IMAP_TIMEOUT:           504,\n  IMAP_MAILBOX_NOT_FOUND: 404,\n  MESSAGE_NOT_FOUND:      404,\n  SMTP_AUTH_FAILED:       401,\n  SMTP_CONNECT_FAILED:    503,\n  SMTP_INVALID_RECIPIENT: 400,\n  VALIDATION_ERROR:       400,\n  INTERNAL_ERROR:         500,\n};\n\n// Human-readable hints per error code\nfunction getHint(code: InboxErrorCode, message: string): string | undefined {\n  switch (code) {\n    case 'ENV_MISSING':\n      return 'Set INBOX_ACCOUNTS=work,personal and account vars (INBOX_ACCOUNT_WORK_USER, _PASS, _IMAP_HOST, _SMTP_HOST)';\n    case 'ACCOUNT_NOT_FOUND':\n      return `Use kb inbox accounts to see configured accounts, then pass the name with --account`;\n    case 'IMAP_AUTH_FAILED':\n      return 'Create an app-password in Yandex ID settings (yandex.ru/id) and set it as INBOX_ACCOUNT_<NAME>_PASS';\n    case 'IMAP_CONNECT_FAILED':\n      return `Check INBOX_ACCOUNT_<NAME>_IMAP_HOST and _IMAP_PORT, and that the server is reachable`;\n    case 'IMAP_TIMEOUT':\n      return 'Server did not respond in time — try again in a moment';\n    case 'IMAP_MAILBOX_NOT_FOUND':\n      return 'Run kb inbox folders --account <name> to see available folders';\n    case 'MESSAGE_NOT_FOUND':\n      return 'The uid may be stale — refresh with: kb inbox list';\n    case 'SMTP_AUTH_FAILED':\n      return 'Create an app-password in Yandex ID settings and set it as INBOX_ACCOUNT_<NAME>_PASS';\n    case 'SMTP_CONNECT_FAILED':\n      return 'Check INBOX_ACCOUNT_<NAME>_SMTP_HOST and _SMTP_PORT';\n    case 'SMTP_INVALID_RECIPIENT':\n      return 'Verify the --to address is a valid email';\n    case 'VALIDATION_ERROR':\n      return undefined; // message itself is descriptive enough\n    case 'INTERNAL_ERROR':\n      return undefined;\n    default: {\n      const _: never = code;\n      void _;\n      return undefined;\n    }\n  }\n}\n\n/**\n * Output a structured error for CLI commands.\n *\n * JSON mode  → { ok: false, error: { code, message, hint? } }  — agent-parseable\n * Human mode → ctx.ui.error() with hint and cause fields\n *\n * Call right before `return { exitCode: 1, result: null }`.\n */\nexport function handleError(ctx: PluginContextV3, err: unknown, isJson?: boolean): void {\n  if (err instanceof InboxError) {\n    const hint = getHint(err.code, err.message);\n\n    if (isJson) {\n      ctx.ui?.json?.({\n        ok: false,\n        error: {\n          code: err.code,\n          message: err.message,\n          ...(hint && { hint }),\n        },\n      });\n    } else {\n      ctx.ui?.error?.(err.message, {\n        ...(hint && { hint }),\n        cause: `InboxError [${err.code}]`,\n      });\n    }\n    return;\n  }\n\n  // Unknown error\n  const message = err instanceof Error ? err.message : String(err);\n\n  if (isJson) {\n    ctx.ui?.json?.({\n      ok: false,\n      error: { code: 'INTERNAL_ERROR', message },\n    });\n  } else {\n    ctx.ui?.error?.(message);\n  }\n}\n\n/**\n * Re-throws err as an HTTP-aware error for REST handlers.\n * InboxError → preserves HTTP status; others → 500.\n */\nexport function rethrowForRest(err: unknown): never {\n  if (err instanceof InboxError) {\n    const hint = getHint(err.code, err.message);\n    throw Object.assign(new Error(err.message), {\n      statusCode: REST_STATUS[err.code] ?? 500,\n      code: err.code,\n      details: hint ? { hint } : undefined,\n    });\n  }\n\n  const message = err instanceof Error ? err.message : String(err);\n  throw Object.assign(new Error(message), {\n    statusCode: 500,\n    code: 'INTERNAL_ERROR',\n  });\n}\n","import { defineCommand, type CLIInput, type PluginContextV3 } from '@kb-labs/sdk';\nimport { resolveAccount, listFolders } from '@kb-labs/inbox-core';\nimport { handleError } from '../utils/error.js';\n\ntype FoldersFlags = {\n  account?: string;\n  json?: boolean;\n};\n\nexport default defineCommand({\n  id: 'inbox:folders',\n  description: 'List available folders/mailboxes',\n\n  handler: {\n    async execute(ctx: PluginContextV3, input: CLIInput<FoldersFlags>) {\n      try {\n        const account = resolveAccount(input.flags.account);\n        const folders = await listFolders(account);\n\n        if (input.flags.json) {\n          ctx.ui?.json?.({ ok: true, result: folders });\n          return { exitCode: 0, result: folders };\n        }\n\n        ctx.ui?.chain?.(folders.map(f => ({\n          title: f.path,\n          sections: [{\n            items: [\n              [\n                f.specialUse ? `special: ${f.specialUse}` : null,\n                f.flags.length ? `flags: ${f.flags.join(' ')}` : null,\n              ].filter(Boolean).join('  ') || '—',\n            ],\n          }],\n        })));\n\n        return { exitCode: 0, result: folders };\n      } catch (err) {\n        handleError(ctx, err, input.flags.json);\n        return { exitCode: 1, result: null };\n      }\n    },\n  },\n});\n"]}

package/dist/commands/mail-get.d.ts

@@ -0,0 +1,14 @@
+import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+import * as _kb_labs_inbox_contracts from '@kb-labs/inbox-contracts';
+import { CLIInput } from '@kb-labs/sdk';
+
+type GetFlags = {
+    folder?: string;
+    attachments?: boolean;
+    account?: string;
+    json?: boolean;
+    full?: boolean;
+};
+declare const _default: _kb_labs_shared_command_kit.CommandHandlerV3<unknown, CLIInput<GetFlags>, _kb_labs_inbox_contracts.Email | null>;
+
+export { _default as default };

package/dist/commands/mail-get.js

@@ -0,0 +1,150 @@
+import { defineCommand, validationError } from '@kb-labs/sdk';
+import { resolveAccount, getMessage, InboxError } from '@kb-labs/inbox-core';
+
+// src/commands/mail-get.ts
+function getHint(code, message) {
+  switch (code) {
+    case "ENV_MISSING":
+      return "Set INBOX_ACCOUNTS=work,personal and account vars (INBOX_ACCOUNT_WORK_USER, _PASS, _IMAP_HOST, _SMTP_HOST)";
+    case "ACCOUNT_NOT_FOUND":
+      return `Use kb inbox accounts to see configured accounts, then pass the name with --account`;
+    case "IMAP_AUTH_FAILED":
+      return "Create an app-password in Yandex ID settings (yandex.ru/id) and set it as INBOX_ACCOUNT_<NAME>_PASS";
+    case "IMAP_CONNECT_FAILED":
+      return `Check INBOX_ACCOUNT_<NAME>_IMAP_HOST and _IMAP_PORT, and that the server is reachable`;
+    case "IMAP_TIMEOUT":
+      return "Server did not respond in time \u2014 try again in a moment";
+    case "IMAP_MAILBOX_NOT_FOUND":
+      return "Run kb inbox folders --account <name> to see available folders";
+    case "MESSAGE_NOT_FOUND":
+      return "The uid may be stale \u2014 refresh with: kb inbox list";
+    case "SMTP_AUTH_FAILED":
+      return "Create an app-password in Yandex ID settings and set it as INBOX_ACCOUNT_<NAME>_PASS";
+    case "SMTP_CONNECT_FAILED":
+      return "Check INBOX_ACCOUNT_<NAME>_SMTP_HOST and _SMTP_PORT";
+    case "SMTP_INVALID_RECIPIENT":
+      return "Verify the --to address is a valid email";
+    case "VALIDATION_ERROR":
+      return void 0;
+    // message itself is descriptive enough
+    case "INTERNAL_ERROR":
+      return void 0;
+    default: {
+      return void 0;
+    }
+  }
+}
+function handleError(ctx, err, isJson) {
+  if (err instanceof InboxError) {
+    const hint = getHint(err.code, err.message);
+    if (isJson) {
+      ctx.ui?.json?.({
+        ok: false,
+        error: {
+          code: err.code,
+          message: err.message,
+          ...hint && { hint }
+        }
+      });
+    } else {
+      ctx.ui?.error?.(err.message, {
+        ...hint && { hint },
+        cause: `InboxError [${err.code}]`
+      });
+    }
+    return;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  if (isJson) {
+    ctx.ui?.json?.({
+      ok: false,
+      error: { code: "INTERNAL_ERROR", message }
+    });
+  } else {
+    ctx.ui?.error?.(message);
+  }
+}
+
+// src/utils/slim.ts
+function formatDate(iso) {
+  const d = new Date(iso);
+  const now = /* @__PURE__ */ new Date();
+  const diff = now.getTime() - d.getTime();
+  if (diff < 6e4) {
+    return "just now";
+  }
+  if (diff < 36e5) {
+    return `${Math.floor(diff / 6e4)}m ago`;
+  }
+  if (diff < 864e5) {
+    return `${Math.floor(diff / 36e5)}h ago`;
+  }
+  if (diff < 7 * 864e5) {
+    return `${Math.floor(diff / 864e5)}d ago`;
+  }
+  return d.toLocaleDateString();
+}
+function formatFrom(from) {
+  return from.name ? `${from.name} <${from.address}>` : from.address;
+}
+
+// src/commands/mail-get.ts
+var mail_get_default = defineCommand({
+  id: "inbox:mail.get",
+  description: "Get full email content by uid",
+  handler: {
+    async execute(ctx, input) {
+      const [rawUid] = input.argv;
+      if (!rawUid) {
+        validationError(ctx, "uid is required", "Usage: kb inbox get <uid>", input.flags.json);
+        return { exitCode: 1, result: null };
+      }
+      const uid = parseInt(rawUid, 10);
+      if (isNaN(uid)) {
+        validationError(ctx, `Invalid uid: "${rawUid}" \u2014 must be a number`, void 0, input.flags.json);
+        return { exitCode: 1, result: null };
+      }
+      try {
+        const account = resolveAccount(input.flags.account);
+        const email = await getMessage(account, uid, {
+          folder: input.flags.folder ?? "INBOX",
+          withAttachments: input.flags.attachments
+        });
+        if (input.flags.json) {
+          ctx.ui?.json?.({ ok: true, result: email });
+          return { exitCode: 0, result: email };
+        }
+        const sections = [];
+        if (email.cc?.length) {
+          sections.push({ header: "CC", items: [email.cc.map((a) => formatFrom(a)).join(", ")] });
+        }
+        if (email.text) {
+          sections.push({ header: "Body", items: [email.text.slice(0, 2e3)] });
+        }
+        if (email.attachments?.length) {
+          sections.push({ header: "Attachments", items: email.attachments.map((a) => `${a.filename} (${a.contentType})`) });
+        }
+        ctx.ui?.sideBox?.({
+          title: `[${email.uid}] ${email.subject}`,
+          status: "info",
+          summary: {
+            "From": formatFrom(email.from),
+            "To": email.to.map((a) => formatFrom(a)).join(", "),
+            "Date": formatDate(email.date),
+            "Folder": email.folder,
+            "Flags": email.flags.join(" ") || "\u2014"
+          },
+          sections
+        });
+        return { exitCode: 0, result: email };
+      } catch (err) {
+        handleError(ctx, err, input.flags.json);
+        return { exitCode: 1, result: null };
+      }
+    }
+  }
+});
+
+export { mail_get_default as default };
+//# sourceMappingURL=mail-get.js.map
+//# sourceMappingURL=mail-get.js.map

package/dist/commands/mail-get.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/error.ts","../../src/utils/slim.ts","../../src/commands/mail-get.ts"],"names":[],"mappings":";;;;AAoBA,SAAS,OAAA,CAAQ,MAAsB,OAAA,EAAqC;AAC1E,EAAA,QAAQ,IAAA;AAAM,IACZ,KAAK,aAAA;AACH,MAAA,OAAO,4GAAA;AAAA,IACT,KAAK,mBAAA;AACH,MAAA,OAAO,CAAA,mFAAA,CAAA;AAAA,IACT,KAAK,kBAAA;AACH,MAAA,OAAO,qGAAA;AAAA,IACT,KAAK,qBAAA;AACH,MAAA,OAAO,CAAA,qFAAA,CAAA;AAAA,IACT,KAAK,cAAA;AACH,MAAA,OAAO,6DAAA;AAAA,IACT,KAAK,wBAAA;AACH,MAAA,OAAO,gEAAA;AAAA,IACT,KAAK,mBAAA;AACH,MAAA,OAAO,yDAAA;AAAA,IACT,KAAK,kBAAA;AACH,MAAA,OAAO,sFAAA;AAAA,IACT,KAAK,qBAAA;AACH,MAAA,OAAO,qDAAA;AAAA,IACT,KAAK,wBAAA;AACH,MAAA,OAAO,0CAAA;AAAA,IACT,KAAK,kBAAA;AACH,MAAA,OAAO,MAAA;AAAA;AAAA,IACT,KAAK,gBAAA;AACH,MAAA,OAAO,MAAA;AAAA,IACT,SAAS;AAGP,MAAA,OAAO,MAAA;AAAA,IACT;AAAA;AAEJ;AAUO,SAAS,WAAA,CAAY,GAAA,EAAsB,GAAA,EAAc,MAAA,EAAwB;AACtF,EAAA,IAAI,eAAe,UAAA,EAAY;AAC7B,IAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,GAAA,CAAI,IAAA,EAAM,IAAI,OAAO,CAAA;AAE1C,IAAA,IAAI,MAAA,EAAQ;AACV,MAAA,GAAA,CAAI,IAAI,IAAA,GAAO;AAAA,QACb,EAAA,EAAI,KAAA;AAAA,QACJ,KAAA,EAAO;AAAA,UACL,MAAM,GAAA,CAAI,IAAA;AAAA,UACV,SAAS,GAAA,CAAI,OAAA;AAAA,UACb,GAAI,IAAA,IAAQ,EAAE,IAAA;AAAK;AACrB,OACD,CAAA;AAAA,IACH,CAAA,MAAO;AACL,MAAA,GAAA,CAAI,EAAA,EAAI,KAAA,GAAQ,GAAA,CAAI,OAAA,EAAS;AAAA,QAC3B,GAAI,IAAA,IAAQ,EAAE,IAAA,EAAK;AAAA,QACnB,KAAA,EAAO,CAAA,YAAA,EAAe,GAAA,CAAI,IAAI,CAAA,CAAA;AAAA,OAC/B,CAAA;AAAA,IACH;AACA,IAAA;AAAA,EACF;AAGA,EAAA,MAAM,UAAU,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU,OAAO,GAAG,CAAA;AAE/D,EAAA,IAAI,MAAA,EAAQ;AACV,IAAA,GAAA,CAAI,IAAI,IAAA,GAAO;AAAA,MACb,EAAA,EAAI,KAAA;AAAA,MACJ,KAAA,EAAO,EAAE,IAAA,EAAM,gBAAA,EAAkB,OAAA;AAAQ,KAC1C,CAAA;AAAA,EACH,CAAA,MAAO;AACL,IAAA,GAAA,CAAI,EAAA,EAAI,QAAQ,OAAO,CAAA;AAAA,EACzB;AACF;;;AChFO,SAAS,WAAW,GAAA,EAAqB;AAC9C,EAAA,MAAM,CAAA,GAAI,IAAI,IAAA,CAAK,GAAG,CAAA;AACtB,EAAA,MAAM,GAAA,uBAAU,IAAA,EAAK;AACrB,EAAA,MAAM,IAAA,GAAO,GAAA,CAAI,OAAA,EAAQ,GAAI,EAAE,OAAA,EAAQ;AAEvC,EAAA,IAAI,OAAO,GAAA,EAAQ;AAAE,IAAA,OAAO,UAAA;AAAA,EAAY;AACxC,EAAA,IAAI,OAAO,IAAA,EAAW;AAAE,IAAA,OAAO,CAAA,EAAG,IAAA,CAAK,KAAA,CAAM,IAAA,GAAO,GAAM,CAAC,CAAA,KAAA,CAAA;AAAA,EAAS;AACpE,EAAA,IAAI,OAAO,KAAA,EAAY;AAAE,IAAA,OAAO,CAAA,EAAG,IAAA,CAAK,KAAA,CAAM,IAAA,GAAO,IAAS,CAAC,CAAA,KAAA,CAAA;AAAA,EAAS;AACxE,EAAA,IAAI,IAAA,GAAO,IAAI,KAAA,EAAY;AAAE,IAAA,OAAO,CAAA,EAAG,IAAA,CAAK,KAAA,CAAM,IAAA,GAAO,KAAU,CAAC,CAAA,KAAA,CAAA;AAAA,EAAS;AAE7E,EAAA,OAAO,EAAE,kBAAA,EAAmB;AAC9B;AAEO,SAAS,WAAW,IAAA,EAAkD;AAC3E,EAAA,OAAO,IAAA,CAAK,OAAO,CAAA,EAAG,IAAA,CAAK,IAAI,CAAA,EAAA,EAAK,IAAA,CAAK,OAAO,CAAA,CAAA,CAAA,GAAM,IAAA,CAAK,OAAA;AAC7D;;;ACjBA,IAAO,mBAAQ,aAAA,CAAc;AAAA,EAC3B,EAAA,EAAI,gBAAA;AAAA,EACJ,WAAA,EAAa,+BAAA;AAAA,EAEb,OAAA,EAAS;AAAA,IACP,MAAM,OAAA,CAAQ,GAAA,EAAsB,KAAA,EAA2B;AAC7D,MAAA,MAAM,CAAC,MAAM,CAAA,GAAI,KAAA,CAAM,IAAA;AACvB,MAAA,IAAI,CAAC,MAAA,EAAQ;AACX,QAAA,eAAA,CAAgB,GAAA,EAAK,iBAAA,EAAmB,2BAAA,EAA6B,KAAA,CAAM,MAAM,IAAI,CAAA;AACrF,QAAA,OAAO,EAAE,QAAA,EAAU,CAAA,EAAG,MAAA,EAAQ,IAAA,EAAK;AAAA,MACrC;AAEA,MAAA,MAAM,GAAA,GAAM,QAAA,CAAS,MAAA,EAAQ,EAAE,CAAA;AAC/B,MAAA,IAAI,KAAA,CAAM,GAAG,CAAA,EAAG;AACd,QAAA,eAAA,CAAgB,KAAK,CAAA,cAAA,EAAiB,MAAM,6BAAwB,MAAA,EAAW,KAAA,CAAM,MAAM,IAAI,CAAA;AAC/F,QAAA,OAAO,EAAE,QAAA,EAAU,CAAA,EAAG,MAAA,EAAQ,IAAA,EAAK;AAAA,MACrC;AAEA,MAAA,IAAI;AACF,QAAA,MAAM,OAAA,GAAU,cAAA,CAAe,KAAA,CAAM,KAAA,CAAM,OAAO,CAAA;AAClD,QAAA,MAAM,KAAA,GAAQ,MAAM,UAAA,CAAW,OAAA,EAAS,GAAA,EAAK;AAAA,UAC3C,MAAA,EAAQ,KAAA,CAAM,KAAA,CAAM,MAAA,IAAU,OAAA;AAAA,UAC9B,eAAA,EAAiB,MAAM,KAAA,CAAM;AAAA,SAC9B,CAAA;AAED,QAAA,IAAI,KAAA,CAAM,MAAM,IAAA,EAAM;AACpB,UAAA,GAAA,CAAI,IAAI,IAAA,GAAO,EAAE,IAAI,IAAA,EAAM,MAAA,EAAQ,OAAO,CAAA;AAC1C,UAAA,OAAO,EAAE,QAAA,EAAU,CAAA,EAAG,MAAA,EAAQ,KAAA,EAAM;AAAA,QACtC;AAEA,QAAA,MAAM,WAAwD,EAAC;AAE/D,QAAA,IAAI,KAAA,CAAM,IAAI,MAAA,EAAQ;AACpB,UAAA,QAAA,CAAS,KAAK,EAAE,MAAA,EAAQ,MAAM,KAAA,EAAO,CAAC,MAAM,EAAA,CAAG,GAAA,CAAI,CAAA,CAAA,KAAK,UAAA,CAAW,CAAC,CAAC,CAAA,CAAE,KAAK,IAAI,CAAC,GAAG,CAAA;AAAA,QACtF;AACA,QAAA,IAAI,MAAM,IAAA,EAAM;AACd,UAAA,QAAA,CAAS,IAAA,CAAK,EAAE,MAAA,EAAQ,MAAA,EAAQ,KAAA,EAAO,CAAC,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,CAAA,EAAG,GAAI,CAAC,GAAG,CAAA;AAAA,QACtE;AACA,QAAA,IAAI,KAAA,CAAM,aAAa,MAAA,EAAQ;AAC7B,UAAA,QAAA,CAAS,KAAK,EAAE,MAAA,EAAQ,aAAA,EAAe,KAAA,EAAO,MAAM,WAAA,CAAY,GAAA,CAAI,CAAA,CAAA,KAAK,CAAA,EAAG,EAAE,QAAQ,CAAA,EAAA,EAAK,EAAE,WAAW,CAAA,CAAA,CAAG,GAAG,CAAA;AAAA,QAChH;AAEA,QAAA,GAAA,CAAI,IAAI,OAAA,GAAU;AAAA,UAChB,OAAO,CAAA,CAAA,EAAI,KAAA,CAAM,GAAG,CAAA,EAAA,EAAK,MAAM,OAAO,CAAA,CAAA;AAAA,UACtC,MAAA,EAAQ,MAAA;AAAA,UACR,OAAA,EAAS;AAAA,YACP,MAAA,EAAU,UAAA,CAAW,KAAA,CAAM,IAAI,CAAA;AAAA,YAC/B,IAAA,EAAU,KAAA,CAAM,EAAA,CAAG,GAAA,CAAI,CAAA,CAAA,KAAK,WAAW,CAAC,CAAC,CAAA,CAAE,IAAA,CAAK,IAAI,CAAA;AAAA,YACpD,MAAA,EAAU,UAAA,CAAW,KAAA,CAAM,IAAI,CAAA;AAAA,YAC/B,UAAU,KAAA,CAAM,MAAA;AAAA,YAChB,OAAA,EAAU,KAAA,CAAM,KAAA,CAAM,IAAA,CAAK,GAAG,CAAA,IAAK;AAAA,WACrC;AAAA,UACA;AAAA,SACD,CAAA;AAED,QAAA,OAAO,EAAE,QAAA,EAAU,CAAA,EAAG,MAAA,EAAQ,KAAA,EAAM;AAAA,MACtC,SAAS,GAAA,EAAK;AACZ,QAAA,WAAA,CAAY,GAAA,EAAK,GAAA,EAAK,KAAA,CAAM,KAAA,CAAM,IAAI,CAAA;AACtC,QAAA,OAAO,EAAE,QAAA,EAAU,CAAA,EAAG,MAAA,EAAQ,IAAA,EAAK;AAAA,MACrC;AAAA,IACF;AAAA;AAEJ,CAAC","file":"mail-get.js","sourcesContent":["import type { PluginContextV3 } from '@kb-labs/sdk';\nimport { InboxError, type InboxErrorCode } from '@kb-labs/inbox-core';\n\n// HTTP status codes for REST layer\nconst REST_STATUS: Record<InboxErrorCode, number> = {\n  ENV_MISSING:            400,\n  ACCOUNT_NOT_FOUND:      400,\n  IMAP_AUTH_FAILED:       401,\n  IMAP_CONNECT_FAILED:    503,\n  IMAP_TIMEOUT:           504,\n  IMAP_MAILBOX_NOT_FOUND: 404,\n  MESSAGE_NOT_FOUND:      404,\n  SMTP_AUTH_FAILED:       401,\n  SMTP_CONNECT_FAILED:    503,\n  SMTP_INVALID_RECIPIENT: 400,\n  VALIDATION_ERROR:       400,\n  INTERNAL_ERROR:         500,\n};\n\n// Human-readable hints per error code\nfunction getHint(code: InboxErrorCode, message: string): string | undefined {\n  switch (code) {\n    case 'ENV_MISSING':\n      return 'Set INBOX_ACCOUNTS=work,personal and account vars (INBOX_ACCOUNT_WORK_USER, _PASS, _IMAP_HOST, _SMTP_HOST)';\n    case 'ACCOUNT_NOT_FOUND':\n      return `Use kb inbox accounts to see configured accounts, then pass the name with --account`;\n    case 'IMAP_AUTH_FAILED':\n      return 'Create an app-password in Yandex ID settings (yandex.ru/id) and set it as INBOX_ACCOUNT_<NAME>_PASS';\n    case 'IMAP_CONNECT_FAILED':\n      return `Check INBOX_ACCOUNT_<NAME>_IMAP_HOST and _IMAP_PORT, and that the server is reachable`;\n    case 'IMAP_TIMEOUT':\n      return 'Server did not respond in time — try again in a moment';\n    case 'IMAP_MAILBOX_NOT_FOUND':\n      return 'Run kb inbox folders --account <name> to see available folders';\n    case 'MESSAGE_NOT_FOUND':\n      return 'The uid may be stale — refresh with: kb inbox list';\n    case 'SMTP_AUTH_FAILED':\n      return 'Create an app-password in Yandex ID settings and set it as INBOX_ACCOUNT_<NAME>_PASS';\n    case 'SMTP_CONNECT_FAILED':\n      return 'Check INBOX_ACCOUNT_<NAME>_SMTP_HOST and _SMTP_PORT';\n    case 'SMTP_INVALID_RECIPIENT':\n      return 'Verify the --to address is a valid email';\n    case 'VALIDATION_ERROR':\n      return undefined; // message itself is descriptive enough\n    case 'INTERNAL_ERROR':\n      return undefined;\n    default: {\n      const _: never = code;\n      void _;\n      return undefined;\n    }\n  }\n}\n\n/**\n * Output a structured error for CLI commands.\n *\n * JSON mode  → { ok: false, error: { code, message, hint? } }  — agent-parseable\n * Human mode → ctx.ui.error() with hint and cause fields\n *\n * Call right before `return { exitCode: 1, result: null }`.\n */\nexport function handleError(ctx: PluginContextV3, err: unknown, isJson?: boolean): void {\n  if (err instanceof InboxError) {\n    const hint = getHint(err.code, err.message);\n\n    if (isJson) {\n      ctx.ui?.json?.({\n        ok: false,\n        error: {\n          code: err.code,\n          message: err.message,\n          ...(hint && { hint }),\n        },\n      });\n    } else {\n      ctx.ui?.error?.(err.message, {\n        ...(hint && { hint }),\n        cause: `InboxError [${err.code}]`,\n      });\n    }\n    return;\n  }\n\n  // Unknown error\n  const message = err instanceof Error ? err.message : String(err);\n\n  if (isJson) {\n    ctx.ui?.json?.({\n      ok: false,\n      error: { code: 'INTERNAL_ERROR', message },\n    });\n  } else {\n    ctx.ui?.error?.(message);\n  }\n}\n\n/**\n * Re-throws err as an HTTP-aware error for REST handlers.\n * InboxError → preserves HTTP status; others → 500.\n */\nexport function rethrowForRest(err: unknown): never {\n  if (err instanceof InboxError) {\n    const hint = getHint(err.code, err.message);\n    throw Object.assign(new Error(err.message), {\n      statusCode: REST_STATUS[err.code] ?? 500,\n      code: err.code,\n      details: hint ? { hint } : undefined,\n    });\n  }\n\n  const message = err instanceof Error ? err.message : String(err);\n  throw Object.assign(new Error(message), {\n    statusCode: 500,\n    code: 'INTERNAL_ERROR',\n  });\n}\n","import type { Email, EmailSlim } from '@kb-labs/inbox-contracts';\n\nexport function slimEmail(email: Email): EmailSlim {\n  return {\n    uid: email.uid,\n    subject: email.subject,\n    from: email.from,\n    date: email.date,\n    folder: email.folder,\n    unread: !email.flags.includes('\\\\Seen'),\n    flagged: email.flags.includes('\\\\Flagged'),\n    hasAttachments: (email.attachments?.length ?? 0) > 0,\n  };\n}\n\nexport function formatDate(iso: string): string {\n  const d = new Date(iso);\n  const now = new Date();\n  const diff = now.getTime() - d.getTime();\n\n  if (diff < 60_000) { return 'just now'; }\n  if (diff < 3_600_000) { return `${Math.floor(diff / 60_000)}m ago`; }\n  if (diff < 86_400_000) { return `${Math.floor(diff / 3_600_000)}h ago`; }\n  if (diff < 7 * 86_400_000) { return `${Math.floor(diff / 86_400_000)}d ago`; }\n\n  return d.toLocaleDateString();\n}\n\nexport function formatFrom(from: { name?: string; address: string }): string {\n  return from.name ? `${from.name} <${from.address}>` : from.address;\n}\n","import { defineCommand, validationError, type CLIInput, type PluginContextV3 } from '@kb-labs/sdk';\nimport { resolveAccount, getMessage } from '@kb-labs/inbox-core';\nimport { handleError } from '../utils/error.js';\nimport { formatDate, formatFrom } from '../utils/slim.js';\n\ntype GetFlags = {\n  folder?: string;\n  attachments?: boolean;\n  account?: string;\n  json?: boolean;\n  full?: boolean;\n};\n\nexport default defineCommand({\n  id: 'inbox:mail.get',\n  description: 'Get full email content by uid',\n\n  handler: {\n    async execute(ctx: PluginContextV3, input: CLIInput<GetFlags>) {\n      const [rawUid] = input.argv;\n      if (!rawUid) {\n        validationError(ctx, 'uid is required', 'Usage: kb inbox get <uid>', input.flags.json);\n        return { exitCode: 1, result: null };\n      }\n\n      const uid = parseInt(rawUid, 10);\n      if (isNaN(uid)) {\n        validationError(ctx, `Invalid uid: \"${rawUid}\" — must be a number`, undefined, input.flags.json);\n        return { exitCode: 1, result: null };\n      }\n\n      try {\n        const account = resolveAccount(input.flags.account);\n        const email = await getMessage(account, uid, {\n          folder: input.flags.folder ?? 'INBOX',\n          withAttachments: input.flags.attachments,\n        });\n\n        if (input.flags.json) {\n          ctx.ui?.json?.({ ok: true, result: email });\n          return { exitCode: 0, result: email };\n        }\n\n        const sections: Array<{ header?: string; items: string[] }> = [];\n\n        if (email.cc?.length) {\n          sections.push({ header: 'CC', items: [email.cc.map(a => formatFrom(a)).join(', ')] });\n        }\n        if (email.text) {\n          sections.push({ header: 'Body', items: [email.text.slice(0, 2000)] });\n        }\n        if (email.attachments?.length) {\n          sections.push({ header: 'Attachments', items: email.attachments.map(a => `${a.filename} (${a.contentType})`) });\n        }\n\n        ctx.ui?.sideBox?.({\n          title: `[${email.uid}] ${email.subject}`,\n          status: 'info',\n          summary: {\n            'From':   formatFrom(email.from),\n            'To':     email.to.map(a => formatFrom(a)).join(', '),\n            'Date':   formatDate(email.date),\n            'Folder': email.folder,\n            'Flags':  email.flags.join(' ') || '—',\n          },\n          sections,\n        });\n\n        return { exitCode: 0, result: email };\n      } catch (err) {\n        handleError(ctx, err, input.flags.json);\n        return { exitCode: 1, result: null };\n      }\n    },\n  },\n});\n"]}

package/dist/commands/mail-list.d.ts

@@ -0,0 +1,16 @@
+import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+import * as _kb_labs_inbox_contracts from '@kb-labs/inbox-contracts';
+import { CLIInput } from '@kb-labs/sdk';
+
+type ListFlags = {
+    folder?: string;
+    unread?: boolean;
+    since?: string;
+    limit?: number;
+    account?: string;
+    json?: boolean;
+    full?: boolean;
+};
+declare const _default: _kb_labs_shared_command_kit.CommandHandlerV3<unknown, CLIInput<ListFlags>, _kb_labs_inbox_contracts.EmailSlim[] | null>;
+
+export { _default as default };