@carrierllc/mcp 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/dist/.metadata_never_index +0 -0
  2. package/dist/apps/app-state.d.ts +19 -0
  3. package/dist/apps/app-state.d.ts.map +1 -0
  4. package/dist/apps/app-state.js +28 -0
  5. package/dist/apps/app-state.js.map +1 -0
  6. package/dist/apps/balance-topup.d.ts +19 -0
  7. package/dist/apps/balance-topup.d.ts.map +1 -0
  8. package/dist/apps/balance-topup.js +121 -0
  9. package/dist/apps/balance-topup.js.map +1 -0
  10. package/dist/apps/fleet-health-app.d.ts +29 -0
  11. package/dist/apps/fleet-health-app.d.ts.map +1 -0
  12. package/dist/apps/fleet-health-app.js +152 -0
  13. package/dist/apps/fleet-health-app.js.map +1 -0
  14. package/dist/apps/index.d.ts +37 -0
  15. package/dist/apps/index.d.ts.map +1 -0
  16. package/dist/apps/index.js +42 -0
  17. package/dist/apps/index.js.map +1 -0
  18. package/dist/apps/provisioning-wizard.d.ts +11 -0
  19. package/dist/apps/provisioning-wizard.d.ts.map +1 -0
  20. package/dist/apps/provisioning-wizard.js +345 -0
  21. package/dist/apps/provisioning-wizard.js.map +1 -0
  22. package/dist/audit.d.ts +31 -0
  23. package/dist/audit.d.ts.map +1 -0
  24. package/dist/audit.js +42 -0
  25. package/dist/audit.js.map +1 -0
  26. package/dist/billing-thresholds.d.ts +71 -0
  27. package/dist/billing-thresholds.d.ts.map +1 -0
  28. package/dist/billing-thresholds.js +238 -0
  29. package/dist/billing-thresholds.js.map +1 -0
  30. package/dist/billing.d.ts +95 -0
  31. package/dist/billing.d.ts.map +1 -0
  32. package/dist/billing.js +239 -0
  33. package/dist/billing.js.map +1 -0
  34. package/dist/clerk.d.ts +125 -0
  35. package/dist/clerk.d.ts.map +1 -0
  36. package/dist/clerk.js +389 -0
  37. package/dist/clerk.js.map +1 -0
  38. package/dist/client.d.ts +12 -15
  39. package/dist/client.d.ts.map +1 -1
  40. package/dist/client.js +56 -53
  41. package/dist/client.js.map +1 -1
  42. package/dist/credits.d.ts +165 -0
  43. package/dist/credits.d.ts.map +1 -0
  44. package/dist/credits.js +483 -0
  45. package/dist/credits.js.map +1 -0
  46. package/dist/index.d.ts +6 -11
  47. package/dist/index.d.ts.map +1 -1
  48. package/dist/index.js +74 -23
  49. package/dist/index.js.map +1 -1
  50. package/dist/intelligence.d.ts +2 -8
  51. package/dist/intelligence.d.ts.map +1 -1
  52. package/dist/intelligence.js +399 -154
  53. package/dist/intelligence.js.map +1 -1
  54. package/dist/list-recent-ocs-events.d.ts +48 -0
  55. package/dist/list-recent-ocs-events.d.ts.map +1 -0
  56. package/dist/list-recent-ocs-events.js +160 -0
  57. package/dist/list-recent-ocs-events.js.map +1 -0
  58. package/dist/manus-client.d.ts +429 -0
  59. package/dist/manus-client.d.ts.map +1 -0
  60. package/dist/manus-client.js +401 -0
  61. package/dist/manus-client.js.map +1 -0
  62. package/dist/manus-common.d.ts +5 -0
  63. package/dist/manus-common.d.ts.map +1 -0
  64. package/dist/manus-common.js +5 -0
  65. package/dist/manus-common.js.map +1 -0
  66. package/dist/manus-schedule.d.ts +74 -0
  67. package/dist/manus-schedule.d.ts.map +1 -0
  68. package/dist/manus-schedule.js +213 -0
  69. package/dist/manus-schedule.js.map +1 -0
  70. package/dist/manus-usage.d.ts +32 -0
  71. package/dist/manus-usage.d.ts.map +1 -0
  72. package/dist/manus-usage.js +120 -0
  73. package/dist/manus-usage.js.map +1 -0
  74. package/dist/manus-webhook.d.ts +60 -0
  75. package/dist/manus-webhook.d.ts.map +1 -0
  76. package/dist/manus-webhook.js +361 -0
  77. package/dist/manus-webhook.js.map +1 -0
  78. package/dist/pricing-tools.d.ts +26 -0
  79. package/dist/pricing-tools.d.ts.map +1 -0
  80. package/dist/pricing-tools.js +428 -0
  81. package/dist/pricing-tools.js.map +1 -0
  82. package/dist/projects-tools.d.ts +39 -0
  83. package/dist/projects-tools.d.ts.map +1 -0
  84. package/dist/projects-tools.js +545 -0
  85. package/dist/projects-tools.js.map +1 -0
  86. package/dist/prompts.d.ts +1 -0
  87. package/dist/prompts.d.ts.map +1 -1
  88. package/dist/prompts.js +1 -0
  89. package/dist/prompts.js.map +1 -1
  90. package/dist/stripe-connect-tools.d.ts +33 -0
  91. package/dist/stripe-connect-tools.d.ts.map +1 -0
  92. package/dist/stripe-connect-tools.js +504 -0
  93. package/dist/stripe-connect-tools.js.map +1 -0
  94. package/dist/timing-safe-equal.d.ts +5 -0
  95. package/dist/timing-safe-equal.d.ts.map +1 -0
  96. package/dist/timing-safe-equal.js +13 -0
  97. package/dist/timing-safe-equal.js.map +1 -0
  98. package/dist/tools-backlog.d.ts +37 -0
  99. package/dist/tools-backlog.d.ts.map +1 -0
  100. package/dist/tools-backlog.js +410 -0
  101. package/dist/tools-backlog.js.map +1 -0
  102. package/dist/tools-carrier-ask.d.ts +138 -0
  103. package/dist/tools-carrier-ask.d.ts.map +1 -0
  104. package/dist/tools-carrier-ask.js +913 -0
  105. package/dist/tools-carrier-ask.js.map +1 -0
  106. package/dist/tools-pricing.d.ts +18 -0
  107. package/dist/tools-pricing.d.ts.map +1 -0
  108. package/dist/tools-pricing.js +172 -0
  109. package/dist/tools-pricing.js.map +1 -0
  110. package/dist/tools-ui-agent-ask.d.ts +29 -0
  111. package/dist/tools-ui-agent-ask.d.ts.map +1 -0
  112. package/dist/tools-ui-agent-ask.js +272 -0
  113. package/dist/tools-ui-agent-ask.js.map +1 -0
  114. package/dist/tools-ui-agent-schedule.d.ts +29 -0
  115. package/dist/tools-ui-agent-schedule.d.ts.map +1 -0
  116. package/dist/tools-ui-agent-schedule.js +517 -0
  117. package/dist/tools-ui-agent-schedule.js.map +1 -0
  118. package/dist/tools-ui-agent.d.ts +40 -0
  119. package/dist/tools-ui-agent.d.ts.map +1 -0
  120. package/dist/tools-ui-agent.js +508 -0
  121. package/dist/tools-ui-agent.js.map +1 -0
  122. package/dist/tools.d.ts +44 -13
  123. package/dist/tools.d.ts.map +1 -1
  124. package/dist/tools.js +892 -210
  125. package/dist/tools.js.map +1 -1
  126. package/dist/types.d.ts +298 -0
  127. package/dist/types.d.ts.map +1 -0
  128. package/dist/types.js +5 -0
  129. package/dist/types.js.map +1 -0
  130. package/package.json +15 -8
package/dist/client.js CHANGED
@@ -1,16 +1,11 @@
1
1
  /**
2
- * eSIMVault OCS API client — stdio edition.
2
+ * eSIMVault OCS API client.
3
+ * All requests are POST to /v1?token=<api_key> with JSON body { methodName: <params> }.
4
+ * Responses: { status: { code, msg }, methodName: { ...data } }.
3
5
  *
4
- * Token held at class level (single-user stdio mode; set once from env).
5
- * All requests: POST ${baseUrl}/v1?token=<api_key> body: { methodName: params }
6
- * Responses: { status: { code, msg }, methodName: { ...data } }
7
- *
8
- * PR #10 broadening:
9
- * params accepts Record<string, unknown> | number | string to support
10
- * bare-scalar OCS methods (listSponsor, listSteeringList, getCustomerTariff,
11
- * listDetailedLocationZone, getSimProviderStatus).
12
- * Fix #14:
13
- * getCustomerTariff response key remapped "listTariffRule" → method key.
6
+ * params may be a plain object OR a bare scalar (number/string) for OCS methods that
7
+ * expect a primitive as the request value rather than a nested object (e.g. listSponsor,
8
+ * listSteeringList, getCustomerTariff, listDetailedLocationZone, getSimProviderStatus).
14
9
  */
15
10
  export class OcsApiError extends Error {
16
11
  code;
@@ -22,15 +17,9 @@ export class OcsApiError extends Error {
22
17
  this.name = "OcsApiError";
23
18
  }
24
19
  }
25
- const RETRY_DELAYS_MS = [250, 500, 1000];
26
- const REQUEST_TIMEOUT_MS = 20_000;
27
20
  export class OcsClient {
28
21
  baseUrl;
29
22
  token;
30
- /**
31
- * @param baseUrl OCS root, e.g. https://ocs.esimvault.cloud (no trailing slash, no /v1)
32
- * @param token API token (from ESIMVAULT_API_TOKEN env)
33
- */
34
23
  constructor(baseUrl, token) {
35
24
  this.baseUrl = baseUrl.replace(/\/+$/, "");
36
25
  this.token = token;
@@ -38,45 +27,59 @@ export class OcsClient {
38
27
  async call(method, params = {}) {
39
28
  const url = `${this.baseUrl}/v1?token=${this.token}`;
40
29
  const body = JSON.stringify({ [method]: params });
41
- let lastError = new OcsApiError(-1, "unreachable", method);
42
- for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {
43
- if (attempt > 0) {
44
- const delay = RETRY_DELAYS_MS[attempt - 1];
45
- if (delay !== undefined) {
46
- await new Promise((r) => setTimeout(r, delay));
47
- }
48
- }
49
- let res;
50
- try {
51
- res = await fetch(url, {
52
- method: "POST",
53
- headers: { "Content-Type": "application/json" },
54
- body,
55
- signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
56
- });
57
- }
58
- catch (err) {
59
- lastError = err;
60
- continue;
61
- }
62
- if (res.status >= 500) {
63
- lastError = new OcsApiError(res.status, `HTTP ${res.status} ${res.statusText}`, method);
64
- continue;
65
- }
66
- if (!res.ok) {
67
- throw new OcsApiError(res.status, `HTTP ${res.status} ${res.statusText}`, method);
68
- }
69
- const json = (await res.json());
70
- if (json.status?.code !== 0) {
71
- throw new OcsApiError(json.status?.code ?? -1, json.status?.msg ?? "Unknown error", method);
30
+ const res = await fetch(url, {
31
+ method: "POST",
32
+ headers: { "Content-Type": "application/json" },
33
+ body,
34
+ });
35
+ if (!res.ok) {
36
+ throw new OcsApiError(res.status, `HTTP ${res.status} ${res.statusText}`, method);
37
+ }
38
+ const json = (await res.json());
39
+ if (json.status?.code !== 0) {
40
+ throw new OcsApiError(json.status?.code ?? -1, json.status?.msg ?? "Unknown error", method);
41
+ }
42
+ // getCustomerTariff response is keyed as "listTariffRule" not "getCustomerTariff"
43
+ if (method === "getCustomerTariff" && json["listTariffRule"] !== undefined) {
44
+ return json["listTariffRule"];
45
+ }
46
+ // GeoSense: live OCS returns coordinates under "subscriberLocation", not the method name
47
+ if (method === "getSubscriberLocationByCellId") {
48
+ const byMethod = json[method];
49
+ if (byMethod !== undefined) {
50
+ return byMethod;
72
51
  }
73
- // Fix #14: getCustomerTariff response is keyed as "listTariffRule"
74
- if (method === "getCustomerTariff" && json["listTariffRule"] !== undefined) {
75
- return json["listTariffRule"];
52
+ if (json["subscriberLocation"] !== undefined) {
53
+ return json["subscriberLocation"];
76
54
  }
77
- return json[method] ?? json;
78
55
  }
79
- throw lastError;
56
+ // Return the method-specific payload
57
+ return json[method] ?? json;
58
+ }
59
+ }
60
+ let _client = null;
61
+ export function getClient() {
62
+ if (!_client) {
63
+ const baseUrl = process.env.ESIMVAULT_BASE_URL;
64
+ const token = process.env.ESIMVAULT_API_TOKEN;
65
+ if (!baseUrl || !token) {
66
+ throw new Error("Missing ESIMVAULT_BASE_URL or ESIMVAULT_API_TOKEN environment variables. " +
67
+ "Set them before starting the MCP server.");
68
+ }
69
+ _client = new OcsClient(baseUrl, token);
70
+ }
71
+ return _client;
72
+ }
73
+ /**
74
+ * Fetch the token owner's reseller ID via getResellerInfo.
75
+ * Used as a fallback when bare-integer methods are called without an explicit resellerId.
76
+ */
77
+ export async function getDefaultResellerId() {
78
+ const info = await getClient().call("getResellerInfo", {});
79
+ const id = info?.id;
80
+ if (typeof id !== "number") {
81
+ throw new Error("Could not determine resellerId from getResellerInfo");
80
82
  }
83
+ return id;
81
84
  }
82
85
  //# sourceMappingURL=client.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,165 @@
1
+ /**
2
+ * Carrier MCP — Credits System v2.0 (Pricing Evolution)
3
+ *
4
+ * Implements credit-based billing inspired by Stripe's Pricing Model Evolution Guide:
5
+ * - Monthly credit allotments per tier (Lovable pattern)
6
+ * - Auto-billed overages when base credits exhausted (Warp pattern)
7
+ * - Credit rollovers for irregular usage (Lovable pattern)
8
+ * - Daily free credits for acquisition (Browserbase/Lovable pattern)
9
+ * - Billing thresholds to prevent bill shock (Hex pattern)
10
+ * - Volume discounts for high-usage customers
11
+ *
12
+ * Storage layout (CARRIER_USERS KV):
13
+ * key: credits:<sub>:<yyyymm> value: CreditLedger
14
+ * key: credits:daily:<sub>:<yyyymmdd> value: DailyFreeCredits
15
+ * key: credits:config:<sub> value: CreditConfig (overrides, thresholds)
16
+ * key: credits:rollover:<sub> value: RolloverBalance
17
+ *
18
+ * Credit economy:
19
+ * 1 tool call = 1 credit (read scope)
20
+ * 1 tool call = 2 credits (write scope)
21
+ * 1 tool call = 5 credits (admin scope)
22
+ * Intelligence composites = 3 credits each
23
+ *
24
+ * Stripe integration:
25
+ * - Overages reported via Stripe Metered Billing (usage_records API)
26
+ * - Billing thresholds trigger Stripe invoice finalization
27
+ * - Credit grants created via Stripe Customer Balance Transactions
28
+ */
29
+ import type { Env } from "./types.js";
30
+ import type { Tier, ScopeToken } from "./billing.js";
31
+ /** Monthly credit allotments per tier */
32
+ export declare const TIER_CREDIT_ALLOTMENTS: Record<Tier, number>;
33
+ /** Daily free credits for all users (acquisition driver) */
34
+ export declare const DAILY_FREE_CREDITS = 50;
35
+ /** Maximum rollover credits (cap at 2x monthly allotment) */
36
+ export declare const ROLLOVER_CAP_MULTIPLIER = 2;
37
+ /** Credit cost per scope */
38
+ export declare const SCOPE_CREDIT_COSTS: Record<ScopeToken | "intelligence", number>;
39
+ /** Volume discount tiers (cumulative monthly usage) */
40
+ export declare const VOLUME_DISCOUNTS: VolumeDiscountTier[];
41
+ /** Default billing threshold (in cents) — triggers invoice at this spend level */
42
+ export declare const DEFAULT_BILLING_THRESHOLD_CENTS = 10000;
43
+ /** Overage price per credit (in cents) — Pro tier */
44
+ export declare const OVERAGE_PRICE_PER_CREDIT_CENTS = 0.1;
45
+ export interface VolumeDiscountTier {
46
+ threshold: number;
47
+ discountPct: number;
48
+ }
49
+ export interface CreditLedger {
50
+ /** Monthly allotment (base + rollover) */
51
+ allotment: number;
52
+ /** Credits consumed this period */
53
+ consumed: number;
54
+ /** Credits from rollovers applied this month */
55
+ rollover_applied: number;
56
+ /** Overage credits consumed beyond allotment */
57
+ overage: number;
58
+ /** Overage amount billed (cents) */
59
+ overage_billed_cents: number;
60
+ /** Whether billing threshold was hit this period */
61
+ threshold_triggered: boolean;
62
+ /** ISO 8601 last updated */
63
+ updated_at: string;
64
+ }
65
+ export interface DailyFreeCredits {
66
+ /** Credits granted today */
67
+ granted: number;
68
+ /** Credits consumed from daily free pool */
69
+ consumed: number;
70
+ /** ISO date (YYYY-MM-DD) */
71
+ date: string;
72
+ }
73
+ export interface CreditConfig {
74
+ /** Custom billing threshold override (cents) */
75
+ billing_threshold_cents: number;
76
+ /** Whether overages are enabled (Pro+) */
77
+ overages_enabled: boolean;
78
+ /** Whether rollovers are enabled (Pro+) */
79
+ rollovers_enabled: boolean;
80
+ /** Custom overage rate override (cents per credit) */
81
+ overage_rate_cents: number;
82
+ /** Volume discount tier override */
83
+ volume_discount_pct: number;
84
+ /** Notification preferences */
85
+ notify_at_pct: number[];
86
+ updated_at: string;
87
+ }
88
+ export interface RolloverBalance {
89
+ /** Unused credits from previous month eligible for rollover */
90
+ credits: number;
91
+ /** Source month (YYYYMM) */
92
+ source_month: string;
93
+ /** Expiry — rollovers expire after 1 month */
94
+ expires_at: string;
95
+ }
96
+ export interface CreditCheckResult {
97
+ allowed: boolean;
98
+ credits_remaining: number;
99
+ daily_free_remaining: number;
100
+ overage_active: boolean;
101
+ overage_amount_cents: number;
102
+ threshold_pct: number;
103
+ tier: Tier;
104
+ volume_discount_pct: number;
105
+ reset_at: string;
106
+ }
107
+ export interface CreditDeductionResult {
108
+ success: boolean;
109
+ credits_deducted: number;
110
+ source: "allotment" | "daily_free" | "overage";
111
+ new_balance: number;
112
+ overage_triggered: boolean;
113
+ threshold_triggered: boolean;
114
+ }
115
+ /**
116
+ * Check if a user has sufficient credits for a tool call.
117
+ * Order of credit consumption:
118
+ * 1. Daily free credits (if available)
119
+ * 2. Monthly allotment (base + rollover)
120
+ * 3. Overage (if enabled for tier)
121
+ */
122
+ export declare function checkCredits(env: Env, sub: string, tier: Tier, scope: ScopeToken | "intelligence"): Promise<CreditCheckResult>;
123
+ /**
124
+ * Deduct credits for a tool call. Fire-and-forget in the hot path.
125
+ *
126
+ * Consumption order:
127
+ * 1. Daily free credits first (lowest cost to user)
128
+ * 2. Monthly allotment
129
+ * 3. Overage (auto-billed, Pro+ only)
130
+ */
131
+ export declare function deductCredits(env: Env, sub: string, tier: Tier, scope: ScopeToken | "intelligence"): void;
132
+ /**
133
+ * Calculate and apply rollover credits from previous month.
134
+ * Called by the monthly cron job (scheduled handler).
135
+ *
136
+ * Rules:
137
+ * - Only Pro+ tiers get rollovers
138
+ * - Rollover = min(unused credits, allotment * ROLLOVER_CAP_MULTIPLIER)
139
+ * - Rollovers expire after 1 month (use-it-or-lose-it next cycle)
140
+ */
141
+ export declare function applyMonthlyRollover(env: Env, sub: string, tier: Tier): Promise<RolloverBalance | null>;
142
+ /**
143
+ * Resolve the applicable volume discount percentage based on cumulative usage.
144
+ */
145
+ export declare function resolveVolumeDiscount(consumed: number): number;
146
+ /**
147
+ * Update a user's credit configuration (admin or self-service).
148
+ */
149
+ export declare function updateCreditConfig(env: Env, sub: string, updates: Partial<CreditConfig>): Promise<CreditConfig>;
150
+ /**
151
+ * Get credit usage summary for a user (used by billing UI).
152
+ */
153
+ export declare function getCreditSummary(env: Env, sub: string, tier: Tier): Promise<{
154
+ ledger: CreditLedger;
155
+ daily_free: DailyFreeCredits;
156
+ config: CreditConfig;
157
+ rollover: RolloverBalance | null;
158
+ volume_discount_pct: number;
159
+ }>;
160
+ /**
161
+ * Issue a credit grant to a customer via Stripe Customer Balance Transactions.
162
+ * Used for promotional credits, referral bonuses, and compensation.
163
+ */
164
+ export declare function issueStripeCredits(env: Env, sub: string, amountCents: number, description: string): Promise<boolean>;
165
+ //# sourceMappingURL=credits.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"credits.d.ts","sourceRoot":"","sources":["../src/credits.ts"],"names":[],"mappings":"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"}