@ganju/utils 0.0.1

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@ganju/utils",
+  "version": "0.0.1",
+  "description": "Shared constants, schemas and helpers for Ganju",
+  "license": "Apache-2.0",
+  "author": "MontoyaAndres <andresmontoyafcb@gmail.com>",
+  "homepage": "https://ganju.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MontoyaAndres/ganju.git",
+    "directory": "packages/utils"
+  },
+  "keywords": [
+    "ganju",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./constants": {
+      "types": "./dist/constants.d.ts",
+      "import": "./dist/constants.js",
+      "require": "./dist/constants.js"
+    },
+    "./base64": {
+      "types": "./dist/base64.d.ts",
+      "import": "./dist/base64.js",
+      "require": "./dist/base64.js"
+    },
+    "./toolCatalog": {
+      "types": "./dist/toolCatalog.d.ts",
+      "import": "./dist/toolCatalog.js",
+      "require": "./dist/toolCatalog.js"
+    },
+    "./cliConstants": {
+      "types": "./dist/cliConstants.d.ts",
+      "import": "./dist/cliConstants.js",
+      "require": "./dist/cliConstants.js"
+    },
+    "./sdkConstants": {
+      "types": "./dist/sdkConstants.d.ts",
+      "import": "./dist/sdkConstants.js",
+      "require": "./dist/sdkConstants.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "clean": "rm -rf dist && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^2.2.0",
+    "dayjs": "^1.11.21",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@ganju/tsconfig": "*",
+    "typescript": "^6.0.3"
+  }
+}

package/src/apiError.ts

@@ -0,0 +1,40 @@
+// API error responses come in two shapes: Zod validation failures arrive as
+// { errors: [{ path, message }] }; everything else as { error: 'message' }.
+// These helpers normalize both so callers don't have to branch every time.
+
+interface ApiErrorBody {
+  error?: unknown;
+  errors?: unknown;
+}
+
+export const isApiError = (data: unknown): boolean => {
+  if (!data || typeof data !== 'object') return false;
+  const body = data as ApiErrorBody;
+  return body.error != null || body.errors != null;
+};
+
+export const getApiErrorMessage = (data: unknown, fallback: string): string => {
+  if (data && typeof data === 'object') {
+    const body = data as ApiErrorBody;
+
+    if (Array.isArray(body.errors)) {
+      const messages = body.errors
+        .map(issue =>
+          issue && typeof issue === 'object'
+            ? (issue as { message?: string }).message
+            : null
+        )
+        .filter((message): message is string => !!message);
+      if (messages.length > 0) return messages.join(', ');
+    }
+
+    if (typeof body.error === 'string') return body.error;
+
+    if (body.error && typeof body.error === 'object') {
+      const message = (body.error as { message?: string }).message;
+      if (message) return message;
+    }
+  }
+
+  return fallback;
+};

package/src/attachment.ts

@@ -0,0 +1,97 @@
+import { constants } from './constants';
+
+// Turning one artifact_resource into the three things a multipart `attachment`
+// field needs — bytes, a mime type, and a filename — is the same branch in every
+// path that delivers a file: the native gmail, outlook and slack handlers, and
+// the custom-code broker's sendFile. A resource is either an object in R2
+// (fileKey) or inline text (content), and the filename fallbacks differ between
+// the two.
+//
+// Size caps deliberately stay at the call sites. Each destination has its own
+// (Gmail caps the combined raw size, Outlook caps per file AND combined, Slack
+// caps per file), and folding them in here would mean a helper that has to know
+// which vendor it is serving.
+
+export interface AttachmentResource {
+  uri: string;
+  fileKey?: string | null;
+  content?: string | null;
+  mimeType?: string | null;
+  fileName?: string | null;
+  title?: string | null;
+}
+
+export interface ResolvedAttachment {
+  bytes: ArrayBuffer;
+  mimeType: string;
+  filename: string;
+}
+
+export type ResolveAttachmentResult =
+  { ok: true; attachment: ResolvedAttachment } | { ok: false; error: string };
+
+/**
+ * Resolve one resource's attachment bytes.
+ *
+ * `readObject` rather than an R2 bucket so this stays free of a workers-types
+ * dependency — @ganju/utils is bundled into every uploaded user script, and the
+ * callers each already hold their own bucket binding.
+ *
+ * `verb` only shapes the error text: Slack "uploads" a file where the two mail
+ * providers "attach" one, and the message is read by a model deciding what to do
+ * next.
+ */
+export const resolveAttachment = async (
+  resource: AttachmentResource,
+  readObject: (key: string) => Promise<ArrayBuffer | null>,
+  verb: 'attach' | 'upload' = 'attach'
+): Promise<ResolveAttachmentResult> => {
+  if (resource.fileKey) {
+    const bytes = await readObject(resource.fileKey);
+    if (!bytes) {
+      return {
+        ok: false,
+        error: `Resource bytes missing in storage for ${resource.uri} (fileKey: ${resource.fileKey})`
+      };
+    }
+    return {
+      ok: true,
+      attachment: {
+        bytes,
+        mimeType:
+          resource.mimeType || constants.MIMETYPE_APPLICATION_OCTET_STREAM,
+        filename:
+          resource.fileName ||
+          resource.title ||
+          resource.uri.split('/').pop() ||
+          'attachment'
+      }
+    };
+  }
+
+  if (resource.content !== null && resource.content !== undefined) {
+    const encoded = new TextEncoder().encode(resource.content);
+    // Sliced to its own buffer: TextEncoder may hand back a view into a larger
+    // allocation, and a Blob built from the whole buffer would carry the slack.
+    const bytes = encoded.buffer.slice(
+      encoded.byteOffset,
+      encoded.byteOffset + encoded.byteLength
+    ) as ArrayBuffer;
+    const base = resource.fileName || resource.title || 'attachment';
+    return {
+      ok: true,
+      attachment: {
+        bytes,
+        mimeType: resource.mimeType || 'text/plain',
+        // Inline resources are text with no extension of their own, and a file
+        // named "Q3 Report" arrives unopenable on most clients.
+        filename: /\.[a-z0-9]+$/i.test(base) ? base : `${base}.txt`
+      }
+    };
+  }
+
+  return {
+    ok: false,
+    error: `Resource ${resource.uri} has no inline content and no file in storage; cannot ${verb}.`
+  };
+};

package/src/base64.ts

@@ -0,0 +1,60 @@
+// Both Cloudflare Workers (with nodejs_compat) and the Node container expose
+// the global Buffer; only pure browsers don't. When available it's an order
+// of magnitude faster than the btoa/charCode loop, which matters once payloads
+// reach tens of megabytes (e.g. a Gmail attachment).
+declare const Buffer:
+  | {
+      from(
+        input: Uint8Array | string,
+        encoding?: string
+      ): { toString(encoding: string): string };
+    }
+  | undefined;
+
+const HAS_BUFFER = typeof Buffer !== 'undefined';
+
+export const bytesToBase64 = (bytes: Uint8Array): string => {
+  if (HAS_BUFFER) return Buffer!.from(bytes).toString('base64');
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++)
+    binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+};
+
+export const base64ToBytes = (b64: string): Uint8Array => {
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+};
+
+export const hexToBytes = (hex: string): Uint8Array => {
+  if (hex.length % 2 !== 0) return new Uint8Array(0);
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+};
+
+export const utf8ToBase64 = (value: string): string => {
+  if (HAS_BUFFER) return Buffer!.from(value, 'utf8').toString('base64');
+  return bytesToBase64(new TextEncoder().encode(value));
+};
+
+export const base64ToUtf8 = (b64: string): string =>
+  new TextDecoder().decode(base64ToBytes(b64));
+
+export const toBase64Url = (b64: string): string =>
+  b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+
+export const fromBase64Url = (b64url: string): string => {
+  const standard = b64url.replace(/-/g, '+').replace(/_/g, '/');
+  return standard.padEnd(Math.ceil(standard.length / 4) * 4, '=');
+};
+
+export const utf8ToBase64Url = (value: string): string =>
+  toBase64Url(utf8ToBase64(value));
+
+export const base64UrlToUtf8 = (b64url: string): string =>
+  base64ToUtf8(fromBase64Url(b64url));

package/src/channelDebounce.ts

@@ -0,0 +1,76 @@
+import { constants } from './constants';
+
+// How a burst of messages from one participant is coalesced into a single turn.
+// The buffer lives in a Durable Object keyed by (channel, conversation,
+// participant) — these helpers are the pieces both sides of that boundary share:
+// the webhook that pushes into the buffer and the DO that flushes it.
+
+// A single inbound message held in the buffer. `externalMessageId` is the
+// platform's own id (Telegram message_id, Slack ts, wamid, Discord message id) —
+// it dedupes platform webhook resends and is recorded on the channel_message row.
+export interface BufferedChannelMessage {
+  text: string;
+  externalMessageId: string | null;
+  receivedAt: number;
+}
+
+// Everything the flush needs to run the turn and deliver the reply, minus the
+// message texts themselves. The newest push wins: a display name or thread id
+// can change mid-burst, and the freshest is the one to answer against.
+// `delivery` is opaque here — each platform stores what its own send path needs
+// (chat id + reply-to, Slack channel + thread_ts, …).
+export interface ChannelBufferEnvelope {
+  channelId: string;
+  platform: string;
+  externalConversationId: string;
+  conversationTitle: string | null;
+  conversationScope: string;
+  externalParticipantId: string;
+  participantDisplayName: string | null;
+  participantMetadata: Record<string, unknown> | null;
+  delivery: Record<string, unknown>;
+}
+
+// The payload the DO hands back to the worker when a batch is ready.
+export interface ChannelBufferFlush {
+  envelope: ChannelBufferEnvelope;
+  messages: BufferedChannelMessage[];
+}
+
+// Read the channel's debounce window off its `config`, clamped to the supported
+// range. An unset value takes the default; an explicit 0 disables buffering, so
+// the channel answers every message as it arrives. Anything malformed (a string,
+// a negative, a value past the cap) falls back to the default rather than
+// throwing — a bad config row must not take a live bot down.
+export const resolveDebounceMs = (config: unknown): number => {
+  const raw = (config as { debounceMs?: unknown } | null)?.debounceMs;
+  if (typeof raw !== 'number' || !Number.isFinite(raw)) {
+    return constants.CHANNEL_DEBOUNCE_DEFAULT_MS;
+  }
+  if (raw === constants.CHANNEL_DEBOUNCE_DISABLED) {
+    return constants.CHANNEL_DEBOUNCE_DISABLED;
+  }
+  if (raw < constants.CHANNEL_DEBOUNCE_MIN_MS) {
+    return constants.CHANNEL_DEBOUNCE_DEFAULT_MS;
+  }
+  return Math.min(raw, constants.CHANNEL_DEBOUNCE_MAX_MS);
+};
+
+// The DO instance name for one participant's burst. Keyed by participant, not
+// just conversation: in a group chat two people asking at once are two separate
+// questions, and merging them into one turn would answer neither well.
+export const channelBufferKey = (
+  channelId: string,
+  externalConversationId: string,
+  externalParticipantId: string
+): string => `${channelId}:${externalConversationId}:${externalParticipantId}`;
+
+// Collapse buffered messages into the single user turn the model sees. Blank
+// fragments are dropped (a bare @mention among real text carries nothing).
+export const joinBufferedMessages = (
+  messages: Array<{ text: string }>
+): string =>
+  messages
+    .map(message => message.text.trim())
+    .filter(Boolean)
+    .join(constants.CHANNEL_DEBOUNCE_JOIN);

package/src/channelNotifier.ts

@@ -0,0 +1,39 @@
+import { constants } from './constants';
+
+export interface ToolStatusEvent {
+  toolName: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface ChannelNotifier {
+  toolStarted: (event: ToolStatusEvent) => Promise<void>;
+}
+
+const TOOL_STATUS_COPY: Record<string, string> = {
+  [constants.RESOURCE_TOOL_KEY_SEND_RESOURCE]: 'Preparing the file to send…',
+  'gmail-send-email': 'Sending the email…',
+  'gmail-reply-email': 'Sending the reply…',
+  'gmail-forward-email': 'Forwarding the email…',
+  'gmail-send-draft': 'Sending the draft…',
+  'gmail-create-draft': 'Saving the draft…',
+  'gmail-update-draft': 'Updating the draft…',
+  'gmail-delete-draft': 'Deleting the draft…',
+  'gmail-trash-email': 'Moving the email to trash…',
+  'gmail-modify-labels': 'Updating email labels…',
+  'gmail-batch-modify-labels': 'Updating email labels…',
+  'outlook-send-email': 'Sending the email…',
+  'outlook-reply-email': 'Sending the reply…',
+  'outlook-forward-email': 'Forwarding the email…',
+  'outlook-send-draft': 'Sending the draft…',
+  'outlook-create-draft': 'Saving the draft…',
+  'outlook-update-draft': 'Updating the draft…',
+  'outlook-delete-draft': 'Deleting the draft…',
+  'outlook-trash-email': 'Moving the email to trash…',
+  'outlook-move-message': 'Moving the email…',
+  'outlook-batch-move-messages': 'Moving the emails…',
+  'web-search': 'Searching the web…',
+  'web-extract': 'Reading the page…'
+};
+
+export const getToolStatusMessage = (toolName: string): string | null =>
+  TOOL_STATUS_COPY[toolName] ?? null;

package/src/chunking.ts

@@ -0,0 +1,131 @@
+import { constants } from './constants';
+
+import type {
+  ExtractedDocument,
+  ExtractedDocumentMetadata
+} from './extractedDocument';
+
+export type Separator = (typeof constants.CHUNK_SEPARATORS)[number];
+
+const trySplit = (text: string, sep: string | RegExp): string[] | null => {
+  if (typeof sep === 'string') {
+    return text.includes(sep) ? text.split(sep) : null;
+  }
+  return sep.test(text) ? text.split(sep) : null;
+};
+
+export const splitRecursive = (
+  text: string,
+  target: number,
+  separators: readonly Separator[] = constants.CHUNK_SEPARATORS
+): string[] => {
+  if (text.length <= target) return [text];
+
+  for (const { split, join } of separators) {
+    const parts = trySplit(text, split);
+    if (!parts) continue;
+    const chunks: string[] = [];
+    let current = '';
+    for (const part of parts) {
+      const piece = current ? current + join + part : part;
+      if (piece.length > target && current) {
+        chunks.push(current);
+        current = part;
+      } else {
+        current = piece;
+      }
+    }
+    if (current) chunks.push(current);
+    return chunks.flatMap(chunk =>
+      chunk.length > target ? splitRecursive(chunk, target, separators) : [chunk]
+    );
+  }
+
+  const chunks: string[] = [];
+  for (let i = 0; i < text.length; i += target) {
+    chunks.push(text.slice(i, i + target));
+  }
+  return chunks;
+};
+
+export const chunkText = (
+  text: string,
+  options?: { targetChars?: number; overlapChars?: number }
+): string[] => {
+  const target = options?.targetChars ?? constants.CHUNK_TARGET_CHARS;
+  const overlap = options?.overlapChars ?? constants.CHUNK_OVERLAP_CHARS;
+
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  if (trimmed.length <= target) return [trimmed];
+
+  const rawChunks = splitRecursive(trimmed, target);
+  const withOverlap: string[] = [];
+  for (let i = 0; i < rawChunks.length; i++) {
+    const prev = i > 0 ? rawChunks[i - 1].slice(-overlap) : '';
+    withOverlap.push((prev ? prev + '\n' : '') + rawChunks[i]);
+  }
+  return withOverlap.filter(c => c.trim().length > 0);
+};
+
+export const buildHeader = (input: {
+  title?: string | null;
+  description?: string | null;
+  uri?: string | null;
+  mimeType?: string | null;
+  fileName?: string | null;
+}): string =>
+  [
+    input.title ? `Title: ${input.title}` : null,
+    input.description ? `Description: ${input.description}` : null,
+    input.uri ? `URI: ${input.uri}` : null,
+    input.mimeType ? `MimeType: ${input.mimeType}` : null,
+    input.fileName ? `FileName: ${input.fileName}` : null
+  ]
+    .filter(Boolean)
+    .join('\n');
+
+export interface ChunkMetadata extends ExtractedDocumentMetadata {
+  chunkIndexInPage: number;
+  chunksInPage: number;
+}
+
+export interface PreparedChunk {
+  content: string;
+  metadata: ChunkMetadata | null;
+}
+
+export const prepareChunks = (
+  header: string,
+  documents: ExtractedDocument[] | null,
+  fallbackContent: string | null,
+  options?: { targetChars?: number; overlapChars?: number }
+): PreparedChunk[] => {
+  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();
+      if (!body) return;
+      const text = docIndex === 0 && header ? `${header}\n\n${body}` : body;
+      const pieces = chunkText(text, options);
+      pieces.forEach((piece, pieceIndex) => {
+        out.push({
+          content: piece,
+          metadata: {
+            ...doc.metadata,
+            chunkIndexInPage: pieceIndex,
+            chunksInPage: pieces.length
+          }
+        });
+      });
+    });
+    return out;
+  }
+
+  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,
+    metadata: null
+  }));
+};

package/src/cliConstants.ts

@@ -0,0 +1,50 @@
+// The handful of constants that get bundled into the published `ganju` CLI,
+// split out of the main constants module for exactly that reason.
+//
+// The same problem `sdkConstants.ts` solves, with a sharper edge. `constants.ts`
+// is one large object literal, so a bundler cannot drop the keys a consumer
+// doesn't touch — and the CLI ships to npm, where those keys would be plan
+// limits, pricing, vendor scopes and internal URLs sitting readable inside a
+// public package. Eight values live here instead, and the main module
+// re-exports them so there is still one definition of each.
+//
+// The rule for this file: nothing lands here unless the CLI reads it, and it
+// imports nothing.
+
+// How `ganju login` identifies itself, and where it listens for the redirect.
+//
+// A fixed port would fail whenever something else already held it, so the CLI
+// binds the first one here that is free. All of them are registered up front
+// rather than only the one that gets used: the provider does implement RFC 8252
+// loopback matching, where the port is ignored for a 127.0.0.0/8 redirect, but
+// that is one library's behaviour and this is a login that has already opened
+// someone's browser by the time it would fail.
+export const CLI_OAUTH_CLIENT_NAME = 'Ganju CLI';
+export const CLI_OAUTH_REDIRECT_PATH = '/callback';
+export const CLI_OAUTH_REDIRECT_PORTS = [8976, 8977, 8978, 8979, 8980];
+
+// `offline_access` is what mints the refresh token; without it a CLI session
+// would end an hour after login.
+export const CLI_OAUTH_SCOPES = [
+  'openid',
+  'profile',
+  'email',
+  'offline_access'
+];
+
+// Refresh this far before the access token actually expires, so a long command
+// can't have its token die mid-request.
+export const CLI_TOKEN_REFRESH_SKEW_SECONDS = 60;
+
+// What `ganju build` rewrites the SDK import to. The deployed script imports the
+// sibling module the publish pipeline attaches, whatever the author typed.
+export const CUSTOM_CODE_SDK_SPECIFIER = './ganju-sdk.js';
+
+// Set well below Cloudflare's own script-size ceiling so a rejection happens
+// with a legible error rather than at deploy time.
+export const CUSTOM_CODE_MAX_BUNDLE_BYTES = 3 * 1024 * 1024;
+
+// The provider `ganju secret` writes under. custom-code secrets are the
+// `ctx.secret(name)` values a user script reads at runtime, addressed by the
+// label in each row's metadata.
+export const CREDENTIAL_PROVIDER_CUSTOM_CODE = 'custom-code' as 'custom-code';

package/src/coerce.ts

@@ -0,0 +1,9 @@
+export const toStringArray = (input: unknown): string[] => {
+  if (Array.isArray(input)) {
+    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 [];
+};