@ganju/utils 0.0.1

package/src/parseHttpError.ts

@@ -0,0 +1,16 @@
+export const parseHttpErrorMessage = async (response: Response): Promise<string> => {
+  const raw = await response.text();
+  if (!raw) return `${response.status} ${response.statusText}`;
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed?.error?.message && typeof parsed.error.message === 'string') {
+      return parsed.error.message;
+    }
+    if (typeof parsed?.error === 'string') return parsed.error;
+    if (typeof parsed?.message === 'string') return parsed.message;
+    return raw;
+  } catch {
+    return raw;
+  }
+};

package/src/planLimitError.ts

@@ -0,0 +1,50 @@
+import { constants } from './constants';
+
+// Thrown when an organization hits a hard plan quota. It carries an explicit
+// HTTP status (402 Payment Required) and a stable `code` so the API's central
+// error handler can return them verbatim and the dashboard can recognise the
+// block and show an "upgrade" call-to-action instead of a generic error.
+export interface PlanLimitDetails {
+  // Which quota was hit — one of constants.PLAN_FEATURE_*.
+  feature: string;
+  // The org's current effective plan (FREE / PRO / ENTERPRISE).
+  plan: string;
+  // The numeric limit that was exceeded, when applicable (e.g. 5 tools).
+  limit?: number | null;
+  // The current usage at the time of the block.
+  used?: number | null;
+}
+
+export class PlanLimitError extends Error {
+  readonly status = 402;
+  readonly code = constants.PLAN_LIMIT_ERROR_CODE;
+  readonly feature: string;
+  readonly plan: string;
+  readonly limit: number | null;
+  readonly used: number | null;
+
+  constructor(message: string, details: PlanLimitDetails) {
+    super(message);
+    this.name = 'PlanLimitError';
+    this.feature = details.feature;
+    this.plan = details.plan;
+    this.limit = details.limit ?? null;
+    this.used = details.used ?? null;
+  }
+
+  // The extra fields merged into the JSON error body so clients get structured
+  // context alongside the message.
+  toBody(): Record<string, unknown> {
+    return {
+      code: this.code,
+      feature: this.feature,
+      plan: this.plan,
+      limit: this.limit,
+      used: this.used,
+      upgrade: true
+    };
+  }
+}
+
+export const isPlanLimitError = (error: unknown): error is PlanLimitError =>
+  error instanceof PlanLimitError;

package/src/processQueueBatch.ts

@@ -0,0 +1,46 @@
+import { isRateLimitError, isTransientInfraError } from './retry';
+import { constants } from './constants';
+
+export interface QueueMessageLike<T> {
+  body: T;
+  ack: () => void;
+  retry: (opts?: { delaySeconds?: number }) => void;
+}
+
+export interface QueueBatchLike<T> {
+  queue: string;
+  messages: readonly QueueMessageLike<T>[];
+}
+
+export interface ProcessQueueBatchHandlers<T> {
+  process: (body: T) => Promise<void>;
+  onError: (error: unknown, body: T, queueName: string) => Promise<void>;
+}
+
+export const processQueueBatch = async <T>(
+  batch: QueueBatchLike<T>,
+  handlers: ProcessQueueBatchHandlers<T>
+): Promise<void> => {
+  for (const message of batch.messages) {
+    try {
+      await handlers.process(message.body);
+      message.ack();
+    } catch (error) {
+      if (isTransientInfraError(error)) {
+        // Transient Cloudflare platform hiccup (e.g. a Durable Object /
+        // Container reset). The job itself is fine, so re-run it after a short
+        // backoff without reporting an error or marking the work failed.
+        message.retry({ delaySeconds: constants.TRANSIENT_BACKOFF_SECONDS });
+        continue;
+      }
+      await handlers.onError(error, message.body, batch.queue);
+      if (isRateLimitError(error)) {
+        message.retry({
+          delaySeconds: constants.RATE_LIMIT_BACKOFF_SECONDS
+        });
+      } else {
+        message.retry();
+      }
+    }
+  }
+};

package/src/reservedToolName.ts

@@ -0,0 +1,27 @@
+import { constants } from './constants';
+
+const RESERVED = new Set(constants.RESERVED_TOOL_NAMES);
+
+/**
+ * Is this MCP tool name reserved by the platform?
+ *
+ * Called on the WRITE path only — when a user names an `http-endpoint` tool or
+ * uploads a `custom-code` manifest. Deliberately NOT applied when reading a
+ * stored row back at boot: tightening this list must never stop an already
+ * installed tool from registering, which would be a silent failure the owner
+ * could only diagnose from logs. A legacy name that is reserved today keeps
+ * working; it simply loses the name to the native tool, because apps/mcp
+ * registers natives first.
+ *
+ * See RESERVED_TOOL_NAME_PREFIXES in constants.ts for why this reserves whole
+ * namespaces rather than the enumerated set of shipped keys.
+ */
+export const isReservedToolName = (name: string): boolean => {
+  const lower = name.toLowerCase();
+  return (
+    RESERVED.has(lower) ||
+    constants.RESERVED_TOOL_NAME_PREFIXES.some(prefix =>
+      lower.startsWith(prefix)
+    )
+  );
+};

package/src/resourceUri.ts

@@ -0,0 +1,17 @@
+import { constants } from './constants';
+
+// The `resource://…` URI the dashboard generates from a title when the author
+// doesn't type one, and the same one the broker derives for a script-created
+// resource that arrives without a uri.
+//
+// Shared rather than duplicated because the two have to agree: a resource a
+// tool writes should be addressable exactly like one a person uploaded, and a
+// script asked to "replace the Q3 report" has to be able to name the row the
+// dashboard created. Hyphens, not the underscores `slugifyTitle` produces —
+// that one names MCP prompts and bot commands, where an underscore is legal and
+// a hyphen isn't.
+export const resourceUriFromTitle = (title: string): string =>
+  `${constants.CUSTOM_CODE_RESOURCE_URI_PREFIX}${title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')}`;

package/src/retry.ts

@@ -0,0 +1,43 @@
+export const sleep = (ms: number): Promise<void> =>
+  new Promise<void>(resolve => setTimeout(resolve, ms));
+
+export const isRateLimitError = (err: unknown): boolean => {
+  const msg = String((err as { message?: unknown })?.message ?? err);
+  return /\b429\b|quota|RESOURCE_EXHAUSTED|rate.?limit/i.test(msg);
+};
+
+// Transient Cloudflare platform errors that are safe to retry as-is: a Durable
+// Object / Container (e.g. the resource-handler) getting evicted or reset
+// mid-request, a code-update eviction, or a dropped internal connection. These
+// are infra hiccups, not job failures, so callers should re-run the job rather
+// than report an error or mark the work failed.
+export const isTransientInfraError = (err: unknown): boolean => {
+  const msg = String((err as { message?: unknown })?.message ?? err);
+  return /object to be reset|Durable Object reset|code (?:was|has been) updated|cannot access storage|Network connection lost|internal error.*Durable Object|Durable Object.*internal error/i.test(
+    msg
+  );
+};
+
+export interface RateLimitRetryOptions {
+  maxAttempts?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+}
+
+export const withRateLimitRetry = async <T>(
+  fn: () => Promise<T>,
+  options: RateLimitRetryOptions = {}
+): Promise<T> => {
+  const { maxAttempts = 5, baseDelayMs = 500, maxDelayMs = 10_000 } = options;
+  let attempt = 0;
+  while (true) {
+    try {
+      return await fn();
+    } catch (err) {
+      attempt += 1;
+      if (attempt >= maxAttempts || !isRateLimitError(err)) throw err;
+      const delay = Math.min(2 ** attempt * baseDelayMs, maxDelayMs);
+      await sleep(delay);
+    }
+  }
+};

package/src/sanitize.ts

@@ -0,0 +1,67 @@
+import { constants } from './constants';
+
+export const decodeEntities = (value: string): string =>
+  value
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, '&');
+
+// Escape a string for safe interpolation into HTML text or double-quoted
+// attribute values. The `&` replacement must run first so the entities added
+// by the later replacements are not double-escaped.
+export const escapeHtml = (value: string): string =>
+  value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+
+export const parseOpenXmlProps = (xml: string): Record<string, string> => {
+  const out: Record<string, string> = {};
+  const re =
+    /<(?:[A-Za-z][\w-]*:)?([A-Za-z][\w-]*)(?:\s[^>]*)?>([^<]*)<\/(?:[A-Za-z][\w-]*:)?\1>/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(xml)) !== null) {
+    const value = decodeEntities(match[2]).trim();
+    if (value) out[match[1]] = value;
+  }
+  return out;
+};
+
+export const stripBase64Images = (text: string): string =>
+  text
+    .replace(/<img\b[^>]*\bsrc=["']?data:image\/[^>]*>/gi, '')
+    .replace(/!\[[^\]]*\]\(\s*data:image\/[^)]*\)/g, '')
+    .replace(constants.BASE64_DATA_URI_RE, '')
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+
+export const sanitizeMetadataString = (value: string): string =>
+  value
+    .replace(constants.BASE64_DATA_URI_RE, '')
+    .replace(constants.RAW_BASE64_BLOB_RE, '')
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '')
+    .trim();
+
+export const serializeMetadataValue = (value: unknown): unknown => {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'string') {
+    const cleaned = sanitizeMetadataString(value);
+    return cleaned || undefined;
+  }
+  if (Array.isArray(value)) return value.map(serializeMetadataValue);
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      const serialized = serializeMetadataValue(v);
+      if (serialized !== undefined) out[k] = serialized;
+    }
+    return out;
+  }
+  return value;
+};