@webbula/mcp 1.0.0

package/README.md

@@ -0,0 +1,150 @@
+# Webbula MCP Server
+
+Expose Webbula's email-intelligence and identity-resolution data to AI agents as
+[Model Context Protocol](https://modelcontextprotocol.io) tools — verify and
+clean email addresses, validate full lead records, run batch files, append
+missing contact data, and check your credit balance. Each verification result
+carries a **trust** block (data provenance and activity history) from Webbula's
+20+ year dataset.
+
+The server is a thin wrapper over the Webbula API: it validates input, calls the
+API over HTTPS, and reshapes the response. It performs no scoring of its own —
+every verdict comes from Webbula.
+
+---
+
+## Tools
+
+7 tools available today, plus 4 data-append tools **coming soon** (🔜). Every tool
+validates input with `zod` before any upstream call and returns the result both
+as pretty-printed text and as `structuredContent`.
+
+| # | Tool | Category | Required params | Optional params |
+|---|------|----------|-----------------|-----------------|
+| 1 | `verify_email` | Email verification | `email` | `profile` |
+| 2 | `hygiene_check` | Email verification | `emails` (array, 1–100) | `profile` |
+| 3 | `validate_lead` | Lead validation | ≥1 of `first_name`, `last_name`, `full_address`, `phone`, `emails` | `profile` |
+| 4 | `upload_file` | Batch (async) | `filename` + `content_base64` **or** `data_source` | `profile`, `url`, `host`, `port`, `username`, `password`, `path`, `secure` |
+| 5 | `file_status` | Batch (async) | `package_name` | — |
+| 6 | `download_results` | Batch (async) | `package_name`, `filename` | — |
+| 7 | `get_credits` | Account | — | — |
+| 8 | `append_email` 🔜 | Data append | ≥1 identifying attribute † | `scope` |
+| 9 | `append_telephone` 🔜 | Data append | ≥1 identifying attribute † | `scope` |
+| 10 | `append_postal` 🔜 | Data append | ≥1 identifying attribute † | `scope` |
+| 11 | `append_automotive` 🔜 | Data append | ≥1 identifying attribute † | `scope` |
+
+> 🔜 **Coming soon.** The four `append_*` (identity-resolution) tools are
+> implemented and registered, but the data-append API endpoint is not yet wired
+> up — these tools will go live once it is available.
+>
+> † The four `append_*` tools share one input: any combination of `first_name`,
+> `last_name`, `email`, `address`, `city`, `state`, `zip5`, `phone` (at least one
+> required), plus an optional `scope` (`individual` / `household` / `both`,
+> default `both`).
+
+### Capability breakdown
+
+- **Email verification & hygiene** — `verify_email` returns a deliverability
+  verdict, any corrected form, and a trust block for a single address;
+  `hygiene_check` runs the same per-email classification + activity history over a
+  list of 1–100.
+- **Lead validation** — `validate_lead` parses and assesses a full contact record
+  (name, postal address, phone) in one call, and runs email hygiene too when
+  `emails` are supplied.
+- **Batch file processing (async)** — `upload_file` submits a file (inline base64
+  or a web/FTP/SSH source) and returns a `package_name`; poll `file_status`, then
+  pull each output with `download_results` (`insert.csv` / `_report.xls`).
+- **Data append (identity resolution) 🔜 coming soon** — the `append_*` tools
+  will resolve a contact from known PII and return one missing data point: email,
+  phone (+ line type), full postal address, or automotive (year/make/model). Built
+  and registered; awaiting the data-append API endpoint.
+- **Account** — `get_credits` reports the remaining balance per billing scenario
+  with an explicit "unlimited" flag (consumes no verification credits).
+
+### Result vocabulary
+
+Verification tools pass the upstream **verdict token** through verbatim as `status`
+(or per-email `result`) and attach a static, documented `label` / `risk` /
+`usable` for known tokens (unknown tokens keep the raw token, friendly fields
+omitted — the wrapper never guesses):
+
+| Token | Label | Risk | Usable |
+|-------|-------|------|--------|
+| `Clean` / `Valid` | Clean / Valid | Low | ✅ true |
+| `Unknown` | Unknown | High to Moderate | — (indeterminate) |
+| `Invalid` | Invalid | Extreme | ❌ false |
+| `Reputation` | Reputation Threat | Extreme | ❌ false |
+| `Fraud` | Fraud Threat | Extreme to High | ❌ false |
+| `Delivery` | Delivery Threat | High | ❌ false |
+| `Conversion` | Conversion Threat | Moderate | ❌ false |
+| `Beta` | Beta Threat | Moderate to Low | ❌ false |
+
+When upstream supplies activity data, a **trust** block is attached:
+`{ data_source, first_seen, last_seen, trajectory }`.
+
+### Resources
+
+This server exposes **no MCP resources** — all functionality is provided through
+the tools above.
+
+---
+
+## Configuration
+
+The package is configured entirely through the **environment** — nothing else is
+required. The API key is held in memory for the duration of a request only; it is
+never logged, persisted, or returned in any tool output or error.
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `WEBBULA_API_KEY` | — | **Required.** Your Webbula API key. Sent upstream as the `X-API-KEY` header. |
+| `PORT` | `3000` | Listen port for the HTTP transport. |
+
+### Applying the configuration
+
+The same tool set runs under two transports; the transport is chosen at launch,
+everything else comes from the environment.
+
+```bash
+# stdio (default) — for a local MCP host that spawns the server
+WEBBULA_API_KEY=wb_your_key npx -y @webbula/mcp
+
+# HTTP transport on port 4000 — for a remote/shared deployment
+WEBBULA_API_KEY=wb_your_key PORT=4000 npx -y @webbula/mcp --http
+```
+
+Most MCP hosts launch the server over stdio and inject the key via `env`
+(Claude Desktop `claude_desktop_config.json` example):
+
+```json
+{
+  "mcpServers": {
+    "webbula": {
+      "command": "npx",
+      "args": ["-y", "@webbula/mcp"],
+      "env": {
+        "WEBBULA_API_KEY": "wb_your_key"
+      }
+    }
+  }
+}
+```
+
+Step-by-step, per-client guides:
+
+- [Claude Desktop](./docs/configuration-claude.md)
+- [VS Code](./docs/configuration-vscode.md)
+- [Cursor](./docs/configuration-cursor.md)
+
+### Notes
+
+- **Authentication model.** The key is configured **once, on the server
+  process**, and every request uses it. The HTTP transport does **not** read a
+  per-request `Authorization` / `X-API-KEY` header from inbound clients — run one
+  server instance per key (per tenant, if you need multiple keys).
+
+---
+
+## License
+
+MIT © Webbula, LLC

package/dist/api/enums.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Webbula response vocabulary — the single source of truth for every documented
+ * enum the API returns, with human-readable labels and descriptions.
+ *
+ * Source of truth: the official "Webbula Hygiene API — Developer Guide" v4.2.22
+ * (§2 Responses and Test Values, §5.2 task status, §6.1 webhook events). The
+ * upstream wire values are terse tokens / single-character flags / day buckets;
+ * the tables below map each one to a friendly label and the verbatim documented
+ * description so the tools can return human-readable statuses.
+ *
+ * These tables are DATA, not logic (constitution principle I): the wrapper still
+ * passes the upstream token through verbatim and only attaches the documented
+ * label/risk/description by static lookup — it never scores or infers a verdict.
+ * Any token absent from a table is surfaced as-is with the friendly fields
+ * omitted (no guessing). Update the table — never the handler — when Webbula
+ * adds a value.
+ *
+ * Only the email-verdict and activity tables are consumed by the current MVP
+ * tools (verify_email / hygiene_check). The name / postal / phone / task / hook
+ * tables are captured here ahead of the lead, batch, and webhook tools so the
+ * raw `context/` reference can be retired.
+ */
+/** Documented risk level for an email verdict (§2.1, verbatim). */
+export type EmailRisk = "Extreme" | "Extreme to High" | "High" | "Moderate" | "Moderate to Low" | "High to Moderate" | "Low";
+export interface EmailVerdictInfo {
+    /** Single-character batch-file flag for this verdict (§2.1). */
+    flag: string;
+    /** Human-readable label for the verdict token. */
+    label: string;
+    /** Documented threat/risk level. */
+    risk: EmailRisk;
+    /** Documented description, verbatim. */
+    description: string;
+    /**
+     * Static usability verdict. `undefined` means "indeterminate" — the agent must
+     * read `status`/`result` and decide; callers OMIT `usable` rather than guess.
+     */
+    usable?: boolean;
+}
+/**
+ * Email verdict tokens (§2.1). The union of the three profile modes (Hygiene +
+ * Verification bundled, Hygiene only, Verification only): the threat categories
+ * R/F/D/C/B plus Invalid/Unknown/Valid (verification) and Clean (hygiene-only).
+ */
+export declare const EMAIL_VERDICTS: Readonly<Record<string, EmailVerdictInfo>>;
+/** Look up an email verdict token; `undefined` for unrecognised tokens. */
+export declare function lookupEmailVerdict(token: string): EmailVerdictInfo | undefined;
+/** Day-bucket tokens shared by `activity_first_seen` / `activity_most_recent_seen`. */
+export declare const ACTIVITY_WINDOWS: Readonly<Record<string, string>>;
+/** `activity_trajectory` values (§2.2) → documented description. */
+export declare const ACTIVITY_TRAJECTORY: Readonly<Record<string, string>>;
+/** Name assessment `status` (§2.3). */
+export declare const NAME_STATUS: Readonly<Record<string, string>>;
+export interface GenderInfo {
+    label: string;
+    description: string;
+}
+/** Modeled `gender` codes (§2.3). */
+export declare const NAME_GENDER: Readonly<Record<string, GenderInfo>>;
+export interface AccuracyReferencePoint {
+    score: string;
+    label: string;
+    description: string;
+}
+/** Documented `accuracy_score` reference points (§2.4) — orientation, not a lookup. */
+export declare const POSTAL_ACCURACY_REFERENCE: ReadonlyArray<AccuracyReferencePoint>;
+/** Phone `status` (§2.5). */
+export declare const PHONE_STATUS: Readonly<Record<string, string>>;
+/** Phone `service_type` (§2.5). */
+export declare const PHONE_SERVICE_TYPE: Readonly<Record<string, string>>;
+export interface TaskStatusInfo {
+    label: string;
+    description: string;
+    /** Terminal statuses produce no further transitions. */
+    terminal: boolean;
+}
+/** Batch task `status` values (§5.2). */
+export declare const TASK_STATUS: Readonly<Record<string, TaskStatusInfo>>;
+/** Webhook event types (§6.1) → documented description. */
+export declare const WEBHOOK_EVENTS: Readonly<Record<string, string>>;

package/dist/api/enums.js

@@ -0,0 +1,230 @@
+/**
+ * Webbula response vocabulary — the single source of truth for every documented
+ * enum the API returns, with human-readable labels and descriptions.
+ *
+ * Source of truth: the official "Webbula Hygiene API — Developer Guide" v4.2.22
+ * (§2 Responses and Test Values, §5.2 task status, §6.1 webhook events). The
+ * upstream wire values are terse tokens / single-character flags / day buckets;
+ * the tables below map each one to a friendly label and the verbatim documented
+ * description so the tools can return human-readable statuses.
+ *
+ * These tables are DATA, not logic (constitution principle I): the wrapper still
+ * passes the upstream token through verbatim and only attaches the documented
+ * label/risk/description by static lookup — it never scores or infers a verdict.
+ * Any token absent from a table is surfaced as-is with the friendly fields
+ * omitted (no guessing). Update the table — never the handler — when Webbula
+ * adds a value.
+ *
+ * Only the email-verdict and activity tables are consumed by the current MVP
+ * tools (verify_email / hygiene_check). The name / postal / phone / task / hook
+ * tables are captured here ahead of the lead, batch, and webhook tools so the
+ * raw `context/` reference can be retired.
+ */
+/**
+ * Email verdict tokens (§2.1). The union of the three profile modes (Hygiene +
+ * Verification bundled, Hygiene only, Verification only): the threat categories
+ * R/F/D/C/B plus Invalid/Unknown/Valid (verification) and Clean (hygiene-only).
+ */
+export const EMAIL_VERDICTS = Object.freeze({
+    Reputation: {
+        flag: "R",
+        label: "Reputation Threat",
+        risk: "Extreme",
+        description: "Hazardous email found in a Reputation category filter",
+        usable: false,
+    },
+    Fraud: {
+        flag: "F",
+        label: "Fraud Threat",
+        risk: "Extreme to High",
+        description: "Hazardous email found in a Fraud category filter",
+        usable: false,
+    },
+    Delivery: {
+        flag: "D",
+        label: "Delivery Threat",
+        risk: "High",
+        description: "Hazardous email found in a Delivery category filter",
+        usable: false,
+    },
+    Conversion: {
+        flag: "C",
+        label: "Conversion Threat",
+        risk: "Moderate",
+        description: "Hazardous email found in a Conversion category filter",
+        usable: false,
+    },
+    Beta: {
+        flag: "B",
+        label: "Beta Threat",
+        risk: "Moderate to Low",
+        description: "Hazardous email found in a Beta category filter",
+        usable: false,
+    },
+    Invalid: {
+        flag: "I",
+        label: "Invalid",
+        risk: "Extreme",
+        description: "Invalid and will bounce",
+        usable: false,
+    },
+    Unknown: {
+        flag: "U",
+        label: "Unknown",
+        risk: "High to Moderate",
+        description: "Verification cannot be determined",
+        // usable intentionally omitted — indeterminate (spec edge case).
+    },
+    Valid: {
+        flag: "V",
+        label: "Valid",
+        risk: "Low",
+        description: "Passed the profile process",
+        usable: true,
+    },
+    Clean: {
+        flag: "G",
+        label: "Clean",
+        risk: "Low",
+        description: "Passed the profile process",
+        usable: true,
+    },
+});
+/** Look up an email verdict token; `undefined` for unrecognised tokens. */
+export function lookupEmailVerdict(token) {
+    return Object.prototype.hasOwnProperty.call(EMAIL_VERDICTS, token)
+        ? EMAIL_VERDICTS[token]
+        : undefined;
+}
+// ---------------------------------------------------------------------------
+// Email activity (§2.2) — `activity_first_seen` / `activity_most_recent_seen`
+// day buckets and `activity_trajectory`.
+// ---------------------------------------------------------------------------
+/** Day-bucket tokens shared by `activity_first_seen` / `activity_most_recent_seen`. */
+export const ACTIVITY_WINDOWS = Object.freeze({
+    "30": "Within the last 30 days",
+    "90": "Within the last 90 days",
+    "180": "Within the last 180 days",
+    "365": "Within the last 365 days",
+    "365+": "Over 365 days ago",
+});
+/** `activity_trajectory` values (§2.2) → documented description. */
+export const ACTIVITY_TRAJECTORY = Object.freeze({
+    "Major Deceleration": "The average activity volume of the email has significantly slowed",
+    "Moderate Deceleration": "The average activity volume of the email has moderately slowed",
+    "Slight Deceleration": "The average activity volume of the email has slightly slowed",
+    Unchanged: "The average activity volume of the email has remained constant",
+    "Slight Acceleration": "The average activity volume of the email has slightly hastened",
+    "Moderate Acceleration": "The average activity volume of the email has moderately hastened",
+    "Major Acceleration": "The average activity volume of the email has significantly hastened",
+});
+// ---------------------------------------------------------------------------
+// Name (§2.3) — `task/lead` (future). `status` + `gender`.
+// ---------------------------------------------------------------------------
+/** Name assessment `status` (§2.3). */
+export const NAME_STATUS = Object.freeze({
+    Valid: "Name that has been assessed as Valid",
+    Invalid: "Name that has been assessed as Invalid",
+});
+/** Modeled `gender` codes (§2.3). */
+export const NAME_GENDER = Object.freeze({
+    M: { label: "Male", description: "Name modeled to an individual who is Male" },
+    LM: {
+        label: "Likely Male",
+        description: "Name modeled to an individual who is Likely Male",
+    },
+    F: { label: "Female", description: "Name modeled to an individual who is Female" },
+    LF: {
+        label: "Likely Female",
+        description: "Name modeled to an individual who is Likely Female",
+    },
+    U: {
+        label: "Undetermined",
+        description: "Name that cannot be modeled for a gender",
+    },
+    NF: {
+        label: "Not Found",
+        description: "Name that is not found in our model",
+    },
+});
+/** Documented `accuracy_score` reference points (§2.4) — orientation, not a lookup. */
+export const POSTAL_ACCURACY_REFERENCE = Object.freeze([
+    {
+        score: "0.00%",
+        label: "Low accuracy",
+        description: "Postal that has received a modeled accuracy score of 0.00% (low accuracy)",
+    },
+    {
+        score: "50.00%",
+        label: "Medium accuracy",
+        description: "Postal that has received a modeled accuracy score of 50.00% (medium accuracy)",
+    },
+    {
+        score: "100.00%",
+        label: "High accuracy",
+        description: "Postal that has received a modeled accuracy score of 100.00% (high accuracy)",
+    },
+]);
+// ---------------------------------------------------------------------------
+// Phone (§2.5) — `task/lead` (future). `status` + `service_type`.
+// ---------------------------------------------------------------------------
+/** Phone `status` (§2.5). */
+export const PHONE_STATUS = Object.freeze({
+    Valid: "Phone number that has been assessed as syntactically Valid",
+    Invalid: "Phone number that has been assessed as syntactically Invalid",
+});
+/** Phone `service_type` (§2.5). */
+export const PHONE_SERVICE_TYPE = Object.freeze({
+    Mobile: "The phone number was assigned by the telco as a Mobile number",
+    Landline: "The phone number was assigned by the telco as a Landline number",
+});
+/** Batch task `status` values (§5.2). */
+export const TASK_STATUS = Object.freeze({
+    preparing: {
+        label: "Preparing",
+        description: "The task is being prepared (uploading, formatting, etc.)",
+        terminal: false,
+    },
+    prepared: {
+        label: "Prepared",
+        description: "The task is prepared and will be executed soon",
+        terminal: false,
+    },
+    running: {
+        label: "Running",
+        description: "The task is running through the profile filters",
+        terminal: false,
+    },
+    finished: {
+        label: "Finished",
+        description: "The task is finished and the results are being compiled",
+        terminal: false,
+    },
+    canceled: {
+        label: "Canceled",
+        description: "The task was canceled (no fields, no records, errors, etc.)",
+        terminal: true,
+    },
+    completed: {
+        label: "Completed",
+        description: "The task is completed and the results are available for download",
+        terminal: true,
+    },
+    unknown: {
+        label: "Unknown",
+        description: "The task is in a transitional status state",
+        terminal: false,
+    },
+});
+// ---------------------------------------------------------------------------
+// Webhook event types (§6.1) — hook/* (future).
+// ---------------------------------------------------------------------------
+/** Webhook event types (§6.1) → documented description. */
+export const WEBHOOK_EVENTS = Object.freeze({
+    "task.status.preparing": "Fires a request to the callback URL when a task is in the preparation stage",
+    "task.status.prepared": "Fires a request to the callback URL when a task is done preparing for execution",
+    "task.status.running": "Fires a request to the callback URL when a task is processing",
+    "task.status.finished": "Fires a request to the callback URL when a task is done processing and the results are being prepared",
+    "task.status.canceled": "Fires a request to the callback URL when a task has been canceled",
+});
+//# sourceMappingURL=enums.js.map

package/dist/api/enums.js.map

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

package/dist/api/types.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Upstream Webbula request/response types, mirroring `.context/openapi.yaml`
+ * (the source of truth, constitution principle I). These describe the wire shape
+ * of the v5 express endpoint and `account/info`; the wrapper reshapes them into
+ * agent-facing results elsewhere (see `src/trust.ts` and the tool handlers).
+ */
+/** One per-email hygiene result (`EmailResult` in the OpenAPI contract). */
+export interface EmailResult {
+    email: string;
+    /** Present only when the upstream corrected a typo. */
+    corrected?: string;
+    activity_first_seen?: string;
+    activity_most_recent_seen?: string;
+    activity_trajectory?: string;
+    /** Verdict token, passed through verbatim (e.g. "Clean"). */
+    result: string;
+}
+/** Shared express result envelope (`ExpressResult`). */
+export interface ExpressResult {
+    success: number;
+    transaction?: string;
+    package_name?: string;
+    profile?: string;
+    emails?: EmailResult[];
+    /** Present on error envelopes (`success: 0`). */
+    errors?: string[];
+}
+/**
+ * v5 express response — `credits_remaining` is numeric (research D2). The field
+ * is omitted upstream when the account is unlimited.
+ */
+export interface ExpressEmailResponseV5 extends ExpressResult {
+    credits_remaining?: number;
+    duration?: number;
+    error?: unknown;
+}
+/** Parsed name assessment (`NameValidationResult`), all parts verbatim. */
+export interface NameValidationResult {
+    prefix?: string;
+    first?: string;
+    middle?: string;
+    last?: string;
+    suffix?: string;
+    /** Modeled gender code (`M`/`LM`/`F`/`LF`/`U`/`NF`), verbatim. */
+    gender?: string;
+    /** `Valid` / `Invalid`, verbatim. */
+    status?: string;
+}
+/** Parsed address assessment (`AddressValidationResult`). */
+export interface AddressValidationResult {
+    zip5?: string;
+    state?: string;
+    city?: string;
+    address?: string;
+    address2?: string;
+    /** Continuous percent string (e.g. `"98.5%"`), passed through verbatim (FR-006). */
+    accuracy_score?: string;
+    lon?: number;
+    lat?: number;
+}
+/** Parsed phone assessment (`PhoneValidationResult`). */
+export interface PhoneValidationResult {
+    number?: string;
+    area_code?: string;
+    prefix?: string;
+    suffix?: string;
+    /** `Mobile` / `Landline`, verbatim. */
+    service_type?: string;
+    /** `Valid` / `Invalid`, verbatim. */
+    status?: string;
+}
+/**
+ * One per-scenario credit entry on the compound response (`CreditEntry`). Note
+ * `records` is a formatted string here (e.g. `"12,345"`), unlike the numeric
+ * `CreditsRemaining.records` on `account/info` — passed through verbatim.
+ */
+export interface CreditEntry {
+    scenario?: string;
+    records?: string;
+}
+/**
+ * `task/lead` compound response (`ExpressCompoundResponse`) — the email
+ * `ExpressResult` plus the optional name/phone/address assessments and the
+ * per-scenario `credits_remaining` array.
+ */
+export interface ExpressCompoundResponse extends ExpressResult {
+    name?: NameValidationResult;
+    phone?: PhoneValidationResult;
+    address?: AddressValidationResult;
+    credits_remaining?: CreditEntry[];
+    duration?: number;
+    error?: unknown;
+}
+/** `task/run` batch submission response (`BatchRunResponse`). */
+export interface BatchRunResponse {
+    success: number;
+    transaction?: string;
+    /** The task handle used to poll status and download results. */
+    package_name?: string;
+    errors?: string[];
+    duration?: number;
+}
+/** `task/info` batch status response (`BatchTaskResponse`). */
+export interface BatchTaskResponse {
+    success: number;
+    transaction?: string;
+    package_name?: string;
+    /** Status token, verbatim (e.g. `running`, `completed`). */
+    status?: string;
+    /** Result files available for download (present once finished). */
+    files?: string[];
+    errors?: string[];
+    duration?: number;
+}
+/** One remaining-credit scenario (`CreditsRemaining`). */
+export interface CreditsRemaining {
+    service?: string;
+    scenario?: string;
+    user?: string;
+    records?: number;
+    /** `false` ⇒ the scenario is unlimited (FR-003). */
+    limited?: boolean;
+}
+/**
+ * Persona data-append response (`POST /v1/append`, feature 006). The endpoint
+ * wraps the appended fields under `data` with a `status` of `"success"`; on
+ * failure it returns a non-2xx with a message. `data` keys vary by the requested
+ * filter (e.g. `email`, `phone`/`phone_type`, postal parts, automotive parts) —
+ * the wrapper passes them through verbatim (constitution principle I).
+ */
+export interface PersonaAppendResponse {
+    /** `"success"` on a match; other values / non-2xx indicate failure. */
+    status?: string;
+    /** Appended data points, keyed by field name — passed through verbatim. */
+    data?: Record<string, unknown>;
+    /** Present on some legacy-style error envelopes. */
+    success?: number;
+    errors?: string[] | string;
+    message?: string;
+}
+/** `account/info` response. With `mode=short` the `key` field is omitted. */
+export interface AccountInfoResponse {
+    success: number;
+    transaction?: string;
+    login?: string;
+    credits_remaining?: CreditsRemaining[];
+    /** API token — omitted when `mode=short`; never surfaced by the wrapper. */
+    key?: string;
+    errors?: string[] | {
+        message?: string;
+    };
+    duration?: number;
+}
+/**
+ * Legacy error envelope (`LegacyErrorResponse`): `success: 0` with verbatim
+ * human-readable messages, sometimes returned even on HTTP 200.
+ */
+export interface LegacyErrorResponse {
+    success: number;
+    transaction?: string;
+    errors?: string[];
+    duration?: number;
+}

package/dist/api/types.js

@@ -0,0 +1,8 @@
+/**
+ * Upstream Webbula request/response types, mirroring `.context/openapi.yaml`
+ * (the source of truth, constitution principle I). These describe the wire shape
+ * of the v5 express endpoint and `account/info`; the wrapper reshapes them into
+ * agent-facing results elsewhere (see `src/trust.ts` and the tool handlers).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}