@ganju/utils 0.0.5 → 0.0.8

package/dist/index.js

@@ -18,6 +18,7 @@ const validateMessageVariables_1 = require("./validateMessageVariables");
 const jsonSchemaToZodShape_1 = require("./jsonSchemaToZodShape");
 const mcpProxy_1 = require("./mcpProxy");
 const customCodeToken_1 = require("./customCodeToken");
+const containmentToken_1 = require("./containmentToken");
 const oauthProviders_1 = require("./oauthProviders");
 const attachment_1 = require("./attachment");
 const exposedResource_1 = require("./exposedResource");
@@ -45,6 +46,7 @@ const channelNotifier_1 = require("./channelNotifier");
 const channelDebounce_1 = require("./channelDebounce");
 const sources_1 = require("./sources");
 const oauth_1 = require("./oauth");
+const vendorTimeZone_1 = require("./vendorTimeZone");
 const planLimitError_1 = require("./planLimitError");
 exports.utils = {
     Schema: schema_1.Schema,
@@ -92,6 +94,8 @@ exports.utils = {
     customCodePreviewScriptName: customCodeToken_1.customCodePreviewScriptName,
     customCodeUploadName: customCodeToken_1.customCodeUploadName,
     customCodePreviewUploadName: customCodeToken_1.customCodePreviewUploadName,
+    mintContainmentToken: containmentToken_1.mintContainmentToken,
+    verifyContainmentToken: containmentToken_1.verifyContainmentToken,
     oauthProviders: oauthProviders_1.oauthProviders,
     resolveAttachment: attachment_1.resolveAttachment,
     isExposedResource: exposedResource_1.isExposedResource,
@@ -157,6 +161,12 @@ exports.utils = {
     buildReauthMetadata: oauth_1.buildReauthMetadata,
     clearReauthMetadata: oauth_1.clearReauthMetadata,
     isCredentialNeedingReauth: oauth_1.isCredentialNeedingReauth,
+    isValidTimeZone: vendorTimeZone_1.isValidTimeZone,
+    readCredentialTimeZone: vendorTimeZone_1.readCredentialTimeZone,
+    credentialTimeZoneIsStale: vendorTimeZone_1.credentialTimeZoneIsStale,
+    writeCredentialTimeZone: vendorTimeZone_1.writeCredentialTimeZone,
+    fetchGoogleCalendarTimeZone: vendorTimeZone_1.fetchGoogleCalendarTimeZone,
+    fetchCalcomTimeZone: vendorTimeZone_1.fetchCalcomTimeZone,
     PlanLimitError: planLimitError_1.PlanLimitError,
     isPlanLimitError: planLimitError_1.isPlanLimitError
 };

package/dist/oauth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;CAKzB;AAUD,eAAO,MAAM,iBAAiB,GAC5B,OAAO,sBAAsB,KAC5B,OAAO,CAAC,mBAAmB,CAsC7B,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACxC,QAAQ,MAAM,KACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAKvB,CAAC;AAEH,eAAO,MAAM,mBAAmB,GAC9B,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,KACvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAO5B,CAAC;AAEF,eAAO,MAAM,yBAAyB,GACpC,UAAU,OAAO,KAChB,OAGF,CAAC"}
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;CAKzB;AAUD,eAAO,MAAM,iBAAiB,GAC5B,OAAO,sBAAsB,KAC5B,OAAO,CAAC,mBAAmB,CAsC7B,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACxC,QAAQ,MAAM,KACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAKvB,CAAC;AAEH,eAAO,MAAM,mBAAmB,GAC9B,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,KACvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAO5B,CAAC;AAEF,eAAO,MAAM,yBAAyB,GAAI,UAAU,OAAO,KAAG,OAG7D,CAAC"}

package/dist/parseHttpError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseHttpError.d.ts","sourceRoot":"","sources":["../src/parseHttpError.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,GAAU,UAAU,QAAQ,KAAG,OAAO,CAAC,MAAM,CAe9E,CAAC"}
+{"version":3,"file":"parseHttpError.d.ts","sourceRoot":"","sources":["../src/parseHttpError.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,GAChC,UAAU,QAAQ,KACjB,OAAO,CAAC,MAAM,CAehB,CAAC"}

package/dist/sources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,MAAM;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,YAAY,MAAM,CAAC,YAAY,CAAC,KAAG,OAEb,CAAC;AAE5D,eAAO,MAAM,uBAAuB,GAClC,UAAU;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,KAC1D,OAEwB,CAAC;AAE5B,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAGnD,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,KAAK,kBAAkB,EACvB,YAAY,MAAM,EAClB,aAAa,MAAM,KAClB,MAGF,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAKD,eAAO,MAAM,sBAAsB,GACjC,SAAS,MAAM,EAAE,EACjB,KAAK,kBAAkB,EACvB,UAAU;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,KACpC,YAAY,EAwBd,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EAAE,EACjB,KAAK,kBAAkB,KACtB,MAmBF,CAAC"}
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,MAAM;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAC/B,YAAY,MAAM,CAAC,YAAY,CAAC,KAC/B,OAEwD,CAAC;AAE5D,eAAO,MAAM,uBAAuB,GAClC,UAAU;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,KAC1D,OAEwB,CAAC;AAE5B,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAGnD,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,KAAK,kBAAkB,EACvB,YAAY,MAAM,EAClB,aAAa,MAAM,KAClB,MAGF,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAKD,eAAO,MAAM,sBAAsB,GACjC,SAAS,MAAM,EAAE,EACjB,KAAK,kBAAkB,EACvB,UAAU;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,KACpC,YAAY,EA2Bd,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EAAE,EACjB,KAAK,kBAAkB,KACtB,MAmBF,CAAC"}

package/dist/vendorError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vendorError.d.ts","sourceRoot":"","sources":["../src/vendorError.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,mBAAmB,GAAI,MAAM,OAAO,EAAE,UAAU,MAAM,KAAG,MASrE,CAAC"}
+{"version":3,"file":"vendorError.d.ts","sourceRoot":"","sources":["../src/vendorError.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,mBAAmB,GAC9B,MAAM,OAAO,EACb,UAAU,MAAM,KACf,MASF,CAAC"}

package/dist/vendorTimeZone.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Is this a time zone the runtime actually knows?
+ *
+ * Everything downstream — `Intl.DateTimeFormat`, Google's `start.timeZone`,
+ * Cal.com's `attendee.timeZone` — throws or 400s on a name it cannot resolve.
+ * A vendor returning something unexpected must degrade to "we don't know"
+ * rather than poison every later call with a value that cannot be used.
+ */
+export declare const isValidTimeZone: (value: unknown) => value is string;
+/** The cached zone on a credential's metadata, or null. */
+export declare const readCredentialTimeZone: (metadata: unknown) => string | null;
+/**
+ * Should we ask the vendor again?
+ *
+ * True when there is nothing cached, when the stamp is missing or unreadable,
+ * or when the TTL has passed. A cache with no stamp is treated as stale rather
+ * than as fresh-forever — the conservative direction, since the only cost is
+ * one request.
+ */
+export declare const credentialTimeZoneIsStale: (metadata: unknown, now?: number) => boolean;
+/**
+ * Merge a freshly read zone into a credential's metadata.
+ *
+ * Merges rather than replaces, because this column also carries the reauth
+ * markers — writing a bare `{ timeZone }` here would clear `needsReauth` and
+ * silently re-enable a connection the refresh path had flagged as broken.
+ *
+ * A null zone (the vendor could not tell us) still stamps the check, so a
+ * provider that never reports one is asked once a day rather than on every
+ * single call.
+ */
+export declare const writeCredentialTimeZone: (previous: unknown, timeZone: string | null, now?: Date) => Record<string, unknown>;
+/**
+ * The zone Google Calendar is configured in, from the primary calendar.
+ *
+ * Deliberately NOT `GET /users/me/settings/timezone`, which is the more
+ * direct answer to "what did the user configure" and needs
+ * `calendar.settings.readonly` — a scope we do not request and could not add
+ * without sending every already-connected user back through consent. The
+ * primary calendar's zone is the same value in every case that matters, and
+ * `calendar.readonly` already covers it.
+ *
+ * Returns null on any failure. Not knowing the zone is a state the callers
+ * handle; a throw here would take a tool call or a chat turn with it.
+ */
+export declare const fetchGoogleCalendarTimeZone: (accessToken: string) => Promise<string | null>;
+/**
+ * The zone on the connected Cal.com profile.
+ *
+ * This is the host's zone — the one their availability is written in — which
+ * is what "9am" means when the artifact owner or their bot says it. It is not
+ * the attendee's zone; see the booking handler for why we use it there anyway.
+ *
+ * Same null-on-failure contract as the Google reader above.
+ */
+export declare const fetchCalcomTimeZone: (apiKey: string) => Promise<string | null>;
+//# sourceMappingURL=vendorTimeZone.d.ts.map

package/dist/vendorTimeZone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vendorTimeZone.d.ts","sourceRoot":"","sources":["../src/vendorTimeZone.ts"],"names":[],"mappings":"AAiCA;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAQzD,CAAC;AAEF,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB,GAAI,UAAU,OAAO,KAAG,MAAM,GAAG,IAInE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,GACpC,UAAU,OAAO,EACjB,MAAK,MAAmB,KACvB,OAOF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,GAClC,UAAU,OAAO,EACjB,UAAU,MAAM,GAAG,IAAI,EACvB,MAAK,IAAiB,KACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAYxB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B,GACtC,aAAa,MAAM,KAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAiBvB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,MAAM,KACb,OAAO,CAAC,MAAM,GAAG,IAAI,CAkBvB,CAAC"}

package/dist/vendorTimeZone.js

@@ -0,0 +1,165 @@
+"use strict";
+// The time zone the user configured with the vendor, and where we keep it.
+//
+// Every scheduling question the model answers is a time-zone question first:
+// "tomorrow at 9" is not an instant until you know whose 9 it is. We had two
+// sources for that and neither worked. `artifact_tool.config.defaultTimeZone`
+// is only written when the owner opens a dropdown and changes it, so in
+// practice it is empty. The fallbacks underneath it were `undefined` (Google
+// then uses the calendar's own zone, which only helps when the timestamp has no
+// offset) and the string 'UTC' (Cal.com, which books the attendee in UTC and
+// tells nobody).
+//
+// But the user already answered this question — in Google Calendar's settings,
+// and in their Cal.com profile. So we ask the vendor instead of asking the
+// owner again, and the answer becomes the default under any explicit choice.
+//
+// It is cached on `artifact_credential.metadata` because that is what it is a
+// property of: the connected account, not the tool row. One artifact can have
+// six calendar tools installed and they all share one connection, so the
+// connection is the only place the answer belongs exactly once.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchCalcomTimeZone = exports.fetchGoogleCalendarTimeZone = exports.writeCredentialTimeZone = exports.credentialTimeZoneIsStale = exports.readCredentialTimeZone = exports.isValidTimeZone = void 0;
+const constants_1 = require("./constants");
+// Metadata keys on artifact_credential. Namespaced with a prefix that will not
+// collide with the reauth markers written by the OAuth refresh path.
+const TIME_ZONE_KEY = 'timeZone';
+const TIME_ZONE_CHECKED_AT_KEY = 'timeZoneCheckedAt';
+// How long a cached zone is trusted. A day, because this changes when somebody
+// moves or travels — rarely, and never urgently. The cost of being briefly
+// stale is one meeting in the old zone; the cost of a shorter TTL is a vendor
+// round trip on the path of a tool call.
+const TIME_ZONE_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Is this a time zone the runtime actually knows?
+ *
+ * Everything downstream — `Intl.DateTimeFormat`, Google's `start.timeZone`,
+ * Cal.com's `attendee.timeZone` — throws or 400s on a name it cannot resolve.
+ * A vendor returning something unexpected must degrade to "we don't know"
+ * rather than poison every later call with a value that cannot be used.
+ */
+const isValidTimeZone = (value) => {
+    if (typeof value !== 'string' || !value.trim())
+        return false;
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: value.trim() });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.isValidTimeZone = isValidTimeZone;
+/** The cached zone on a credential's metadata, or null. */
+const readCredentialTimeZone = (metadata) => {
+    if (!metadata || typeof metadata !== 'object')
+        return null;
+    const value = metadata[TIME_ZONE_KEY];
+    return (0, exports.isValidTimeZone)(value) ? value.trim() : null;
+};
+exports.readCredentialTimeZone = readCredentialTimeZone;
+/**
+ * Should we ask the vendor again?
+ *
+ * True when there is nothing cached, when the stamp is missing or unreadable,
+ * or when the TTL has passed. A cache with no stamp is treated as stale rather
+ * than as fresh-forever — the conservative direction, since the only cost is
+ * one request.
+ */
+const credentialTimeZoneIsStale = (metadata, now = Date.now()) => {
+    if (!(0, exports.readCredentialTimeZone)(metadata))
+        return true;
+    const raw = metadata[TIME_ZONE_CHECKED_AT_KEY];
+    if (typeof raw !== 'string')
+        return true;
+    const checkedAt = Date.parse(raw);
+    if (!Number.isFinite(checkedAt))
+        return true;
+    return now - checkedAt >= TIME_ZONE_TTL_MS;
+};
+exports.credentialTimeZoneIsStale = credentialTimeZoneIsStale;
+/**
+ * Merge a freshly read zone into a credential's metadata.
+ *
+ * Merges rather than replaces, because this column also carries the reauth
+ * markers — writing a bare `{ timeZone }` here would clear `needsReauth` and
+ * silently re-enable a connection the refresh path had flagged as broken.
+ *
+ * A null zone (the vendor could not tell us) still stamps the check, so a
+ * provider that never reports one is asked once a day rather than on every
+ * single call.
+ */
+const writeCredentialTimeZone = (previous, timeZone, now = new Date()) => {
+    const base = previous && typeof previous === 'object'
+        ? { ...previous }
+        : {};
+    if ((0, exports.isValidTimeZone)(timeZone)) {
+        base[TIME_ZONE_KEY] = timeZone.trim();
+    }
+    else {
+        delete base[TIME_ZONE_KEY];
+    }
+    base[TIME_ZONE_CHECKED_AT_KEY] = now.toISOString();
+    return base;
+};
+exports.writeCredentialTimeZone = writeCredentialTimeZone;
+/**
+ * The zone Google Calendar is configured in, from the primary calendar.
+ *
+ * Deliberately NOT `GET /users/me/settings/timezone`, which is the more
+ * direct answer to "what did the user configure" and needs
+ * `calendar.settings.readonly` — a scope we do not request and could not add
+ * without sending every already-connected user back through consent. The
+ * primary calendar's zone is the same value in every case that matters, and
+ * `calendar.readonly` already covers it.
+ *
+ * Returns null on any failure. Not knowing the zone is a state the callers
+ * handle; a throw here would take a tool call or a chat turn with it.
+ */
+const fetchGoogleCalendarTimeZone = async (accessToken) => {
+    try {
+        const response = await fetch(`${constants_1.constants.GOOGLE_CALENDAR_API_BASE}/calendars/primary`, {
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                Accept: 'application/json'
+            }
+        });
+        if (!response.ok)
+            return null;
+        const payload = (await response.json());
+        return (0, exports.isValidTimeZone)(payload?.timeZone) ? payload.timeZone.trim() : null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.fetchGoogleCalendarTimeZone = fetchGoogleCalendarTimeZone;
+/**
+ * The zone on the connected Cal.com profile.
+ *
+ * This is the host's zone — the one their availability is written in — which
+ * is what "9am" means when the artifact owner or their bot says it. It is not
+ * the attendee's zone; see the booking handler for why we use it there anyway.
+ *
+ * Same null-on-failure contract as the Google reader above.
+ */
+const fetchCalcomTimeZone = async (apiKey) => {
+    try {
+        const response = await fetch(`${constants_1.constants.CALCOM_API_BASE}/me`, {
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'cal-api-version': constants_1.constants.CALCOM_API_VERSION_ME,
+                Accept: 'application/json'
+            }
+        });
+        if (!response.ok)
+            return null;
+        const payload = (await response.json());
+        const value = payload?.data?.timeZone;
+        return (0, exports.isValidTimeZone)(value) ? value.trim() : null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.fetchCalcomTimeZone = fetchCalcomTimeZone;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganju/utils",
-  "version": "0.0.5",
+  "version": "0.0.8",
   "description": "Shared constants, schemas and helpers for Ganju",
   "license": "Apache-2.0",
   "author": "MontoyaAndres <andresmontoyafcb@gmail.com>",

package/src/attachment.ts

@@ -28,7 +28,8 @@ export interface ResolvedAttachment {
 }
 
 export type ResolveAttachmentResult =
-  { ok: true; attachment: ResolvedAttachment } | { ok: false; error: string };
+  | { ok: true; attachment: ResolvedAttachment }
+  | { ok: false; error: string };
 
 /**
  * Resolve one resource's attachment bytes.

package/src/chunking.ts

@@ -37,7 +37,9 @@ export const splitRecursive = (
     }
     if (current) chunks.push(current);
     return chunks.flatMap(chunk =>
-      chunk.length > target ? splitRecursive(chunk, target, separators) : [chunk]
+      chunk.length > target
+        ? splitRecursive(chunk, target, separators)
+        : [chunk]
     );
   }
 
@@ -104,7 +106,9 @@ export const prepareChunks = (
   if (documents && documents.length > 0) {
     const out: PreparedChunk[] = [];
     documents.forEach((doc, docIndex) => {
-      const body = (doc.pageContent || '').replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '').trim();
+      const body = (doc.pageContent || '')
+        .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '')
+        .trim();
       if (!body) return;
       const text = docIndex === 0 && header ? `${header}\n\n${body}` : body;
       const pieces = chunkText(text, options);
@@ -122,7 +126,9 @@ export const prepareChunks = (
     return out;
   }
 
-  const body = (fallbackContent || '').replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '').trim();
+  const body = (fallbackContent || '')
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '')
+    .trim();
   const fullText = [header, body].filter(Boolean).join('\n\n');
   return chunkText(fullText, options).map(content => ({
     content,

package/src/coerce.ts

@@ -3,7 +3,10 @@ export const toStringArray = (input: unknown): string[] => {
     return input.map(s => String(s).trim()).filter(Boolean);
   }
   if (typeof input === 'string' && input.trim()) {
-    return input.split(',').map(s => s.trim()).filter(Boolean);
+    return input
+      .split(',')
+      .map(s => s.trim())
+      .filter(Boolean);
   }
   return [];
 };

package/src/constants.ts

@@ -1054,6 +1054,7 @@ const CALCOM_API_BASE = 'https://api.cal.com/v2';
 const CALCOM_API_VERSION_EVENT_TYPES = '2024-06-14';
 const CALCOM_API_VERSION_SLOTS = '2024-09-04';
 const CALCOM_API_VERSION_BOOKINGS = '2026-02-25';
+const CALCOM_API_VERSION_ME = '2024-06-14';
 
 const CALCOM_TOOL_KEY_PREFIX = 'calcom-';
 
@@ -1810,7 +1811,8 @@ const PLAN_PRO = 'PRO' as 'PRO';
 const PLAN_ENTERPRISE = 'ENTERPRISE' as 'ENTERPRISE';
 const PLANS = [PLAN_FREE, PLAN_PRO, PLAN_ENTERPRISE];
 
-// Mirror Stripe's subscription statuses so the webhook can store them verbatim.
+// The provider's subscription statuses, mirrored so the webhook can store them
+// verbatim.
 const SUBSCRIPTION_STATUS_ACTIVE = 'active' as 'active';
 const SUBSCRIPTION_STATUS_TRIALING = 'trialing' as 'trialing';
 const SUBSCRIPTION_STATUS_PAST_DUE = 'past_due' as 'past_due';
@@ -1890,6 +1892,30 @@ const PRICING_SHARED_KEY_HARD_CAP = 100_000;
 // so $2 is now roughly break-even. Raising CHUNK_TARGET_CHARS would tip it
 // positive without touching this number.
 const PRICING_EMBEDDED_PER_GB_USD = 2;
+// Custom-tool invocations included per month, and the rate beyond them.
+//
+// "Tool call" here means one dispatch into a user's own script on Workers for
+// Platforms — NOT a call to a shipped integration or a proxied server. Those
+// cost us one screened fetch from a Worker we already pay for, which is why they
+// stay bundled; this one runs the customer's code on our infrastructure, and is
+// the first cost axis a user can turn against us rather than merely consume.
+//
+// Cloudflare bills the whole chain (dispatcher → user script → outbound worker)
+// as ONE request and counts CPU across all three, so a call costs ~$2.30 per
+// million at the per-script CPU ceiling. $5/M is ~2x that, and 1,000,000 is far
+// past any real month: the heaviest worked customer in the cost model makes
+// 800,000, and a single artifact pinned at its rate limit for a full month
+// manages ~2.6 million.
+const PRICING_INCLUDED_TOOL_CALLS = 1_000_000;
+const PRICING_TOOL_CALL_PER_M_USD = 5;
+// Abuse backstop on custom-tool invocations — the compute analogue of
+// PRICING_SHARED_KEY_HARD_CAP, and needed for the same reason: past a point,
+// usage stops looking like a customer and starts looking like a runaway loop or
+// a stolen credential. 20x the included allowance is ~$46 of compute against
+// ~$95 billed, and takes eight artifacts held at their rate limit for a month to
+// reach. Enterprise is null — the cost model's own enterprise example makes 20
+// million calls a month, so a fixed ceiling there would fight a real customer.
+const PRICING_TOOL_CALL_HARD_CAP = 20_000_000;
 const PRICING_CUSTOM_DOMAIN_USD = 15;
 
 interface PlanLimits {
@@ -1933,6 +1959,20 @@ interface PlanLimits {
   // keeps that from becoming an unbounded tool list on the plan that runs on our
   // model key. `null` = no limit.
   maxHttpEndpointsPerArtifact: number | null;
+  // Monthly allowance of CUSTOM-TOOL invocations — dispatches into the org's own
+  // code. A billing threshold like includedSharedMessages, not a block: past it
+  // paid plans keep running and meter at the per-million rate.
+  //
+  // Only custom code counts. A shipped integration or a proxied server costs one
+  // screened fetch, so metering those would bill a customer for something that
+  // rounds to zero and make the tool list a thing to ration.
+  includedToolCalls: number;
+  // Absolute stop on custom-tool invocations, regardless of billing. The
+  // compute-side twin of sharedKeyHardCap, and the only limit on this axis that
+  // an infinite loop inside someone's tool actually meets — the per-script CPU
+  // ceiling bounds one call, the per-artifact rate limiter bounds calls per
+  // minute, and this bounds the month. `null` = no backstop.
+  toolCallHardCap: number | null;
   // Display-only allowances included in the plan (what overage is measured
   // against). Not used for blocking.
   includedMessages: number;
@@ -1966,6 +2006,15 @@ const PLAN_LIMITS: Record<
     canUseCustomLlm: false,
     canUseCustomCode: false,
     maxHttpEndpointsPerArtifact: 3,
+    // Free can't deploy custom code, so the only way to have a running script on
+    // this plan is to have DOWNGRADED with one already published — a paid org
+    // keeps its versions and their bundles. Those tools go on serving, because
+    // killing a customer's live integrations the moment a card fails is a worse
+    // failure than serving a bounded number of calls while they fix it. This is
+    // that bound: real breathing room, ~$0.02 of compute, and no overage path
+    // off Free to turn it into a bill.
+    includedToolCalls: 0,
+    toolCallHardCap: 10_000,
     includedMessages: 100,
     includedEmbeddedBytes: 5 * MB
   },
@@ -1987,6 +2036,8 @@ const PLAN_LIMITS: Record<
     canUseCustomLlm: true,
     canUseCustomCode: true,
     maxHttpEndpointsPerArtifact: null,
+    includedToolCalls: PRICING_INCLUDED_TOOL_CALLS,
+    toolCallHardCap: PRICING_TOOL_CALL_HARD_CAP,
     includedMessages: PRICING_INCLUDED_MESSAGES,
     includedEmbeddedBytes: PRICING_INCLUDED_EMBEDDED_GB * GB
   },
@@ -2004,6 +2055,12 @@ const PLAN_LIMITS: Record<
     canUseCustomLlm: true,
     canUseCustomCode: true,
     maxHttpEndpointsPerArtifact: null,
+    includedToolCalls: PRICING_INCLUDED_TOOL_CALLS,
+    // No backstop: an Enterprise contract is negotiated against real volume, and
+    // the reference deal in the cost model runs 20 million calls a month — the
+    // exact number a Pro-shaped ceiling would refuse. Raise the ceiling by
+    // contract; don't make one plan's abuse limit another plan's product limit.
+    toolCallHardCap: null,
     includedMessages: PRICING_INCLUDED_MESSAGES,
     includedEmbeddedBytes: PRICING_INCLUDED_EMBEDDED_GB * GB
   }
@@ -2023,21 +2080,46 @@ const PLAN_FEATURE_HTTP_ENDPOINT = 'httpEndpoint' as 'httpEndpoint';
 const PLAN_FEATURE_RAW_STORAGE = 'rawStorage' as 'rawStorage';
 const PLAN_FEATURE_EMBEDDED_STORAGE = 'embeddedStorage' as 'embeddedStorage';
 const PLAN_FEATURE_MESSAGE = 'message' as 'message';
+const PLAN_FEATURE_TOOL_CALL = 'toolCall' as 'toolCall';
 
 // Stable code returned on a quota block so clients can branch on it (402).
 const PLAN_LIMIT_ERROR_CODE = 'PLAN_LIMIT_EXCEEDED';
 
-// Stripe Billing Meter event names. The metering cron reports per-period
-// OVERAGE (usage above the plan's included allowance) to these meters; the
-// meters' prices on the subscription turn that into charges. Embedded storage
-// is reported in whole MB, messages as a raw count.
+// Billing meter event names. The metering cron reports per-period OVERAGE
+// (usage above the plan's included allowance) to these meters; the meters'
+// prices on the subscribed product turn that into charges. Embedded storage is
+// reported in whole MB, messages as a raw count.
+//
+// Each name must match the filter on its meter exactly. A mismatch is not an
+// error at either end — the event is accepted, matches no meter, and the usage
+// is silently unbilled.
 //
 // Messages report to two separate meters because the two kinds of turn bill at
 // different rates — a turn on the org's own key is a platform fee, a turn on our
 // model is inference we bought. One meter can't price both.
-const STRIPE_METER_MESSAGES = 'ganju_channel_messages';
-const STRIPE_METER_SHARED_MESSAGES = 'ganju_shared_messages';
-const STRIPE_METER_EMBEDDED = 'ganju_embedded_storage';
+const BILLING_METER_MESSAGES = 'ganju_channel_messages';
+const BILLING_METER_SHARED_MESSAGES = 'ganju_shared_messages';
+const BILLING_METER_EMBEDDED = 'ganju_embedded_storage';
+// Custom-tool invocations, reported as a raw count of the calls above the
+// included allowance and priced per call at $5/1,000,000. Metered prices are
+// per single unit, so a partial block is billed as the fraction it is — a
+// customer 2.5 million past the allowance owes $12.50, which is what every page
+// of ours quotes.
+const BILLING_METER_TOOL_CALLS = 'ganju_custom_tool_calls';
+
+// The metadata property every meter aggregates (`sum` over it). Ingested events
+// carry the increment under this key, so it has to agree with the aggregation
+// configured on all four meters — which is why it lives beside their names
+// rather than at the call site.
+const BILLING_METER_UNITS_KEY = 'units';
+
+// Polar API hosts. Sandbox is a separate host rather than a mode flag, so the
+// account, products, meters and webhook secret there are all distinct from
+// production's — which is what `POLAR_SERVER` selects between.
+const POLAR_API_BASE = 'https://api.polar.sh';
+const POLAR_SANDBOX_API_BASE = 'https://sandbox-api.polar.sh';
+const POLAR_SERVER_SANDBOX = 'sandbox' as 'sandbox';
+const POLAR_SERVER_PRODUCTION = 'production' as 'production';
 
 // Legal documents a user accepts, and the version they're on. Bump the version
 // when the document changes materially — existing users are then re-prompted,
@@ -2046,7 +2128,7 @@ const STRIPE_METER_EMBEDDED = 'ganju_embedded_storage';
 const CONSENT_DOCUMENT_TERMS = 'terms' as 'terms';
 const CONSENT_DOCUMENT_PRIVACY = 'privacy' as 'privacy';
 const CONSENT_DOCUMENTS = [CONSENT_DOCUMENT_TERMS, CONSENT_DOCUMENT_PRIVACY];
-const CONSENT_CURRENT_VERSION = '2026-08-01';
+const CONSENT_CURRENT_VERSION = '2026-08-31';
 
 const CONSENT_SOURCE_SIGNUP = 'signup' as 'signup';
 const CONSENT_SOURCE_REACCEPT = 'reaccept' as 'reaccept';
@@ -2086,6 +2168,40 @@ const CRON_HOURLY = '0 * * * *';
 const CRON_ERROR_ALERTS = '*/15 * * * *';
 
 const ALERT_STATE_KEY_ERROR_LOG = 'error_log';
+// Custom-tool usage alerting, keyed per organization as `tool_calls:<id>`. The
+// monthly hard cap bounds what abuse can spend; these thresholds are what say
+// something is happening NOW, while there is still a month left to spend.
+const ALERT_STATE_KEY_TOOL_CALLS = 'tool_calls';
+// Calls in a single hour. The per-tool rate limit allows 3,600/hour, and a month
+// of the included million sustained is ~1,370/hour — so five figures in one hour
+// is either many artifacts at full tilt or something that should be looked at.
+const ALERT_TOOL_CALL_SURGE = 10_000;
+// The share of the abuse backstop at which the wall is close enough to warn
+// about. Half a month's ceiling reached is worth an email even if the rate is
+// unremarkable, because the alternative is a customer meeting it silently.
+const ALERT_TOOL_CALL_CAP_FRACTION = 0.5;
+// How long to stay quiet about one organization after alerting on it. Without
+// this a busy month is an hourly email, and an hourly email is a muted one.
+const ALERT_TOOL_CALL_COOLDOWN_HOURS = 6;
+// Organizations itemised in one digest.
+const ALERT_TOOL_CALL_MAX_ROWS = 25;
+
+// The "stop these tools" link the usage digest carries.
+//
+// It exists because the alert travels and the response did not: every other
+// containment step needs a shell holding the production database URL, so an
+// abuse notice arriving away from a desk was one nobody could act on for hours.
+//
+// Narrow on purpose. It disables the organization's custom-code installs — the
+// tools stop registering at boot, the code, versions and settings all survive,
+// and any owner can switch them back on. It cannot delete a script, touch a
+// credential, or reach anything else.
+const CONTAINMENT_TOKEN_VERSION = '1';
+const CONTAINMENT_PURPOSE_DISABLE_CUSTOM_CODE = 'disable-custom-code';
+// Long enough to still work when the mail is read a few hours late, short enough
+// that a forwarded thread or an archived inbox is not a way in.
+const CONTAINMENT_TOKEN_TTL_MS = 12 * 60 * 60 * 1000;
+const CONTAINMENT_PATH = '/containment';
 // Only alert on genuine server failures. 4xx rows are expected client errors
 // (validation, not-found, quota) and would drown the signal.
 const ALERT_MIN_STATUS = 500;
@@ -2130,6 +2246,9 @@ export const constants = {
   PRICING_INCLUDED_EMBEDDED_GB,
   PRICING_MESSAGE_PER_1K_USD,
   PRICING_EMBEDDED_PER_GB_USD,
+  PRICING_INCLUDED_TOOL_CALLS,
+  PRICING_TOOL_CALL_PER_M_USD,
+  PRICING_TOOL_CALL_HARD_CAP,
   PRICING_CUSTOM_DOMAIN_USD,
   PLAN_FEATURE_ORGANIZATION,
   PLAN_FEATURE_PROJECT,
@@ -2143,10 +2262,17 @@ export const constants = {
   PLAN_FEATURE_RAW_STORAGE,
   PLAN_FEATURE_EMBEDDED_STORAGE,
   PLAN_FEATURE_MESSAGE,
+  PLAN_FEATURE_TOOL_CALL,
   PLAN_LIMIT_ERROR_CODE,
-  STRIPE_METER_MESSAGES,
-  STRIPE_METER_SHARED_MESSAGES,
-  STRIPE_METER_EMBEDDED,
+  BILLING_METER_MESSAGES,
+  BILLING_METER_SHARED_MESSAGES,
+  BILLING_METER_EMBEDDED,
+  BILLING_METER_TOOL_CALLS,
+  BILLING_METER_UNITS_KEY,
+  POLAR_API_BASE,
+  POLAR_SANDBOX_API_BASE,
+  POLAR_SERVER_SANDBOX,
+  POLAR_SERVER_PRODUCTION,
   CONSENT_DOCUMENT_TERMS,
   CONSENT_DOCUMENT_PRIVACY,
   CONSENT_DOCUMENTS,
@@ -2160,6 +2286,15 @@ export const constants = {
   CRON_HOURLY,
   CRON_ERROR_ALERTS,
   ALERT_STATE_KEY_ERROR_LOG,
+  ALERT_STATE_KEY_TOOL_CALLS,
+  ALERT_TOOL_CALL_SURGE,
+  ALERT_TOOL_CALL_CAP_FRACTION,
+  ALERT_TOOL_CALL_COOLDOWN_HOURS,
+  ALERT_TOOL_CALL_MAX_ROWS,
+  CONTAINMENT_TOKEN_VERSION,
+  CONTAINMENT_PURPOSE_DISABLE_CUSTOM_CODE,
+  CONTAINMENT_TOKEN_TTL_MS,
+  CONTAINMENT_PATH,
   ALERT_MIN_STATUS,
   ALERT_MAX_ROWS,
   ALERT_MAX_GROUPS,
@@ -2478,6 +2613,7 @@ export const constants = {
   CALCOM_API_VERSION_EVENT_TYPES,
   CALCOM_API_VERSION_SLOTS,
   CALCOM_API_VERSION_BOOKINGS,
+  CALCOM_API_VERSION_ME,
   CALCOM_TOOL_KEY_PREFIX,
   TAVILY_API_BASE,
   TAVILY_SEARCH_DEPTH_BASIC,