@carrierllc/mcp 0.1.0 → 0.2.0
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.
- package/dist/apps/app-state.d.ts +19 -0
- package/dist/apps/app-state.d.ts.map +1 -0
- package/dist/apps/app-state.js +28 -0
- package/dist/apps/app-state.js.map +1 -0
- package/dist/apps/balance-topup.d.ts +19 -0
- package/dist/apps/balance-topup.d.ts.map +1 -0
- package/dist/apps/balance-topup.js +121 -0
- package/dist/apps/balance-topup.js.map +1 -0
- package/dist/apps/fleet-health-app.d.ts +29 -0
- package/dist/apps/fleet-health-app.d.ts.map +1 -0
- package/dist/apps/fleet-health-app.js +152 -0
- package/dist/apps/fleet-health-app.js.map +1 -0
- package/dist/apps/index.d.ts +37 -0
- package/dist/apps/index.d.ts.map +1 -0
- package/dist/apps/index.js +42 -0
- package/dist/apps/index.js.map +1 -0
- package/dist/apps/provisioning-wizard.d.ts +11 -0
- package/dist/apps/provisioning-wizard.d.ts.map +1 -0
- package/dist/apps/provisioning-wizard.js +345 -0
- package/dist/apps/provisioning-wizard.js.map +1 -0
- package/dist/audit.d.ts +31 -0
- package/dist/audit.d.ts.map +1 -0
- package/dist/audit.js +42 -0
- package/dist/audit.js.map +1 -0
- package/dist/billing-thresholds.d.ts +71 -0
- package/dist/billing-thresholds.d.ts.map +1 -0
- package/dist/billing-thresholds.js +238 -0
- package/dist/billing-thresholds.js.map +1 -0
- package/dist/billing.d.ts +95 -0
- package/dist/billing.d.ts.map +1 -0
- package/dist/billing.js +239 -0
- package/dist/billing.js.map +1 -0
- package/dist/clerk.d.ts +125 -0
- package/dist/clerk.d.ts.map +1 -0
- package/dist/clerk.js +389 -0
- package/dist/clerk.js.map +1 -0
- package/dist/client.d.ts +12 -15
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +48 -55
- package/dist/client.js.map +1 -1
- package/dist/credits.d.ts +165 -0
- package/dist/credits.d.ts.map +1 -0
- package/dist/credits.js +483 -0
- package/dist/credits.js.map +1 -0
- package/dist/index.d.ts +6 -11
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +74 -23
- package/dist/index.js.map +1 -1
- package/dist/intelligence.d.ts +2 -8
- package/dist/intelligence.d.ts.map +1 -1
- package/dist/intelligence.js +321 -154
- package/dist/intelligence.js.map +1 -1
- package/dist/list-recent-ocs-events.d.ts +48 -0
- package/dist/list-recent-ocs-events.d.ts.map +1 -0
- package/dist/list-recent-ocs-events.js +160 -0
- package/dist/list-recent-ocs-events.js.map +1 -0
- package/dist/manus-client.d.ts +429 -0
- package/dist/manus-client.d.ts.map +1 -0
- package/dist/manus-client.js +401 -0
- package/dist/manus-client.js.map +1 -0
- package/dist/manus-common.d.ts +5 -0
- package/dist/manus-common.d.ts.map +1 -0
- package/dist/manus-common.js +5 -0
- package/dist/manus-common.js.map +1 -0
- package/dist/manus-schedule.d.ts +74 -0
- package/dist/manus-schedule.d.ts.map +1 -0
- package/dist/manus-schedule.js +213 -0
- package/dist/manus-schedule.js.map +1 -0
- package/dist/manus-usage.d.ts +32 -0
- package/dist/manus-usage.d.ts.map +1 -0
- package/dist/manus-usage.js +120 -0
- package/dist/manus-usage.js.map +1 -0
- package/dist/manus-webhook.d.ts +60 -0
- package/dist/manus-webhook.d.ts.map +1 -0
- package/dist/manus-webhook.js +361 -0
- package/dist/manus-webhook.js.map +1 -0
- package/dist/pricing-tools.d.ts +26 -0
- package/dist/pricing-tools.d.ts.map +1 -0
- package/dist/pricing-tools.js +428 -0
- package/dist/pricing-tools.js.map +1 -0
- package/dist/projects-tools.d.ts +39 -0
- package/dist/projects-tools.d.ts.map +1 -0
- package/dist/projects-tools.js +545 -0
- package/dist/projects-tools.js.map +1 -0
- package/dist/prompts.d.ts +1 -0
- package/dist/prompts.d.ts.map +1 -1
- package/dist/prompts.js +1 -0
- package/dist/prompts.js.map +1 -1
- package/dist/stripe-connect-tools.d.ts +33 -0
- package/dist/stripe-connect-tools.d.ts.map +1 -0
- package/dist/stripe-connect-tools.js +504 -0
- package/dist/stripe-connect-tools.js.map +1 -0
- package/dist/timing-safe-equal.d.ts +5 -0
- package/dist/timing-safe-equal.d.ts.map +1 -0
- package/dist/timing-safe-equal.js +13 -0
- package/dist/timing-safe-equal.js.map +1 -0
- package/dist/tools-backlog.d.ts +28 -0
- package/dist/tools-backlog.d.ts.map +1 -0
- package/dist/tools-backlog.js +315 -0
- package/dist/tools-backlog.js.map +1 -0
- package/dist/tools-carrier-ask.d.ts +138 -0
- package/dist/tools-carrier-ask.d.ts.map +1 -0
- package/dist/tools-carrier-ask.js +913 -0
- package/dist/tools-carrier-ask.js.map +1 -0
- package/dist/tools-pricing.d.ts +18 -0
- package/dist/tools-pricing.d.ts.map +1 -0
- package/dist/tools-pricing.js +172 -0
- package/dist/tools-pricing.js.map +1 -0
- package/dist/tools-ui-agent-ask.d.ts +29 -0
- package/dist/tools-ui-agent-ask.d.ts.map +1 -0
- package/dist/tools-ui-agent-ask.js +272 -0
- package/dist/tools-ui-agent-ask.js.map +1 -0
- package/dist/tools-ui-agent-schedule.d.ts +29 -0
- package/dist/tools-ui-agent-schedule.d.ts.map +1 -0
- package/dist/tools-ui-agent-schedule.js +517 -0
- package/dist/tools-ui-agent-schedule.js.map +1 -0
- package/dist/tools-ui-agent.d.ts +40 -0
- package/dist/tools-ui-agent.d.ts.map +1 -0
- package/dist/tools-ui-agent.js +508 -0
- package/dist/tools-ui-agent.js.map +1 -0
- package/dist/tools.d.ts +44 -13
- package/dist/tools.d.ts.map +1 -1
- package/dist/tools.js +794 -201
- package/dist/tools.js.map +1 -1
- package/dist/types.d.ts +291 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +5 -0
- package/dist/types.js.map +1 -0
- package/package.json +14 -8
package/dist/client.js
CHANGED
|
@@ -1,16 +1,11 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* eSIMVault OCS API client
|
|
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
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
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,49 @@ 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
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
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);
|
|
72
|
-
}
|
|
73
|
-
// Fix #14: getCustomerTariff response is keyed as "listTariffRule"
|
|
74
|
-
if (method === "getCustomerTariff" && json["listTariffRule"] !== undefined) {
|
|
75
|
-
return json["listTariffRule"];
|
|
76
|
-
}
|
|
77
|
-
return json[method] ?? json;
|
|
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
|
+
// Return the method-specific payload
|
|
47
|
+
return json[method] ?? json;
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
let _client = null;
|
|
51
|
+
export function getClient() {
|
|
52
|
+
if (!_client) {
|
|
53
|
+
const baseUrl = process.env.ESIMVAULT_BASE_URL;
|
|
54
|
+
const token = process.env.ESIMVAULT_API_TOKEN;
|
|
55
|
+
if (!baseUrl || !token) {
|
|
56
|
+
throw new Error("Missing ESIMVAULT_BASE_URL or ESIMVAULT_API_TOKEN environment variables. " +
|
|
57
|
+
"Set them before starting the MCP server.");
|
|
78
58
|
}
|
|
79
|
-
|
|
59
|
+
_client = new OcsClient(baseUrl, token);
|
|
60
|
+
}
|
|
61
|
+
return _client;
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Fetch the token owner's reseller ID via getResellerInfo.
|
|
65
|
+
* Used as a fallback when bare-integer methods are called without an explicit resellerId.
|
|
66
|
+
*/
|
|
67
|
+
export async function getDefaultResellerId() {
|
|
68
|
+
const info = await getClient().call("getResellerInfo", {});
|
|
69
|
+
const id = info?.id;
|
|
70
|
+
if (typeof id !== "number") {
|
|
71
|
+
throw new Error("Could not determine resellerId from getResellerInfo");
|
|
80
72
|
}
|
|
73
|
+
return id;
|
|
81
74
|
}
|
|
82
75
|
//# sourceMappingURL=client.js.map
|
package/dist/client.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA
|
|
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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"}
|