@ganju/utils 0.0.1

package/dist/toolCatalog.d.ts

@@ -0,0 +1,452 @@
+export interface CatalogTool {
+    key: string;
+    title: string;
+    description: string | null;
+    requiredScopes: string | null;
+}
+export interface CatalogGroup {
+    key: string;
+    title: string;
+    description: string | null;
+    icon: string | null;
+    provider: string | null;
+    tools: readonly CatalogTool[];
+}
+export declare const TOOL_CATALOG: readonly [{
+    readonly key: "gmail";
+    readonly title: "Gmail";
+    readonly description: "Send, read, search, and manage emails";
+    readonly icon: "https://www.gstatic.com/images/branding/product/1x/gmail_2020q4_48dp.png";
+    readonly provider: "google-gmail";
+    readonly tools: readonly [{
+        readonly key: "gmail-batch-modify-labels";
+        readonly title: "Batch Modify Labels";
+        readonly description: "Add or remove labels on many emails at once (archive, mark read, etc.).";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.modify";
+    }, {
+        readonly key: "gmail-create-draft";
+        readonly title: "Create Draft";
+        readonly description: "Save a new draft in Gmail without sending it yet.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.compose";
+    }, {
+        readonly key: "gmail-delete-draft";
+        readonly title: "Delete Draft";
+        readonly description: "Permanently delete a draft.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.compose";
+    }, {
+        readonly key: "gmail-forward-email";
+        readonly title: "Forward Email";
+        readonly description: "Forward an email to a new recipient.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.send";
+    }, {
+        readonly key: "gmail-get-draft";
+        readonly title: "Get Draft";
+        readonly description: "Open a saved draft to review its contents.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.compose";
+    }, {
+        readonly key: "gmail-get-profile";
+        readonly title: "Get Profile";
+        readonly description: "Show the email address and inbox stats for the connected Gmail account.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.readonly";
+    }, {
+        readonly key: "gmail-get-thread";
+        readonly title: "Get Thread";
+        readonly description: "See every message inside one conversation.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.readonly";
+    }, {
+        readonly key: "gmail-list-drafts";
+        readonly title: "List Drafts";
+        readonly description: "Browse your saved drafts.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.compose";
+    }, {
+        readonly key: "gmail-list-emails";
+        readonly title: "List Emails";
+        readonly description: "Browse your Gmail inbox, with optional search filters.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.readonly";
+    }, {
+        readonly key: "gmail-list-labels";
+        readonly title: "List Labels";
+        readonly description: "See all of your Gmail labels and folders.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.labels";
+    }, {
+        readonly key: "gmail-list-threads";
+        readonly title: "List Threads";
+        readonly description: "List your Gmail conversations.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.readonly";
+    }, {
+        readonly key: "gmail-modify-labels";
+        readonly title: "Modify Labels";
+        readonly description: "Add or remove labels on a single email — archive it, mark it read, star it, and more.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.modify";
+    }, {
+        readonly key: "gmail-read-email";
+        readonly title: "Read Email";
+        readonly description: "Open and read a specific email.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.readonly";
+    }, {
+        readonly key: "gmail-reply-email";
+        readonly title: "Reply Email";
+        readonly description: "Reply to an email so the response stays in the same conversation.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.send";
+    }, {
+        readonly key: "gmail-send-draft";
+        readonly title: "Send Draft";
+        readonly description: "Send a draft you've already saved.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.send";
+    }, {
+        readonly key: "gmail-send-email";
+        readonly title: "Send Email";
+        readonly description: "Compose and send a new email from your connected Gmail account.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.send";
+    }, {
+        readonly key: "gmail-trash-email";
+        readonly title: "Move to Trash";
+        readonly description: "Move an email to Trash. It stays recoverable for 30 days.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.modify";
+    }, {
+        readonly key: "gmail-update-draft";
+        readonly title: "Update Draft";
+        readonly description: "Edit the contents of a saved draft.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/gmail.compose";
+    }];
+}, {
+    readonly key: "outlook";
+    readonly title: "Outlook";
+    readonly description: "Microsoft Outlook mail tools backed by Microsoft Graph.";
+    readonly icon: "https://api.iconify.design/vscode-icons:file-type-outlook.svg";
+    readonly provider: "microsoft-outlook";
+    readonly tools: readonly [{
+        readonly key: "outlook-batch-move-messages";
+        readonly title: "Batch Move Messages";
+        readonly description: "Move up to 20 messages to the same folder.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.ReadWrite";
+    }, {
+        readonly key: "outlook-create-draft";
+        readonly title: "Create Draft";
+        readonly description: "Create a draft email saved in Drafts.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.ReadWrite";
+    }, {
+        readonly key: "outlook-delete-draft";
+        readonly title: "Delete Draft";
+        readonly description: "Permanently delete a draft.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.ReadWrite";
+    }, {
+        readonly key: "outlook-forward-email";
+        readonly title: "Forward";
+        readonly description: "Forward an existing message to a new recipient.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.Send";
+    }, {
+        readonly key: "outlook-get-draft";
+        readonly title: "Get Draft";
+        readonly description: "Read the full contents of a draft.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.Read";
+    }, {
+        readonly key: "outlook-get-profile";
+        readonly title: "Get Profile";
+        readonly description: "Get the connected account's profile and inbox totals.";
+        readonly requiredScopes: "https://graph.microsoft.com/User.Read";
+    }, {
+        readonly key: "outlook-get-thread";
+        readonly title: "Get Thread";
+        readonly description: "Get summaries of every message in a conversation.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.Read";
+    }, {
+        readonly key: "outlook-list-drafts";
+        readonly title: "List Drafts";
+        readonly description: "List drafts in the Drafts folder.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.Read";
+    }, {
+        readonly key: "outlook-list-emails";
+        readonly title: "List Emails";
+        readonly description: "List inbox messages, optionally filtered by search.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.Read";
+    }, {
+        readonly key: "outlook-list-folders";
+        readonly title: "List Folders";
+        readonly description: "List every mail folder on the account.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.Read";
+    }, {
+        readonly key: "outlook-list-threads";
+        readonly title: "List Threads";
+        readonly description: "List inbox conversation threads.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.Read";
+    }, {
+        readonly key: "outlook-move-message";
+        readonly title: "Move Message";
+        readonly description: "Move a message to a different folder.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.ReadWrite";
+    }, {
+        readonly key: "outlook-read-email";
+        readonly title: "Read Email";
+        readonly description: "Read the full contents of one message by ID.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.Read";
+    }, {
+        readonly key: "outlook-reply-email";
+        readonly title: "Reply";
+        readonly description: "Reply to an existing message, preserving the conversation.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.Send";
+    }, {
+        readonly key: "outlook-send-draft";
+        readonly title: "Send Draft";
+        readonly description: "Send an existing draft as-is.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.Send";
+    }, {
+        readonly key: "outlook-send-email";
+        readonly title: "Send Email";
+        readonly description: "Send a brand-new email from the connected account.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.Send";
+    }, {
+        readonly key: "outlook-trash-email";
+        readonly title: "Move to Trash";
+        readonly description: "Move a message to the Deleted Items folder.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.ReadWrite";
+    }, {
+        readonly key: "outlook-update-draft";
+        readonly title: "Update Draft";
+        readonly description: "Replace the contents of an existing draft.";
+        readonly requiredScopes: "https://graph.microsoft.com/Mail.ReadWrite";
+    }];
+}, {
+    readonly key: "slack";
+    readonly title: "Slack";
+    readonly description: "Post messages, browse channels, and upload files in Slack via Web API.";
+    readonly icon: "https://api.iconify.design/logos:slack-icon.svg";
+    readonly provider: "slack";
+    readonly tools: readonly [{
+        readonly key: "slack-get-user";
+        readonly title: "Get User";
+        readonly description: "Look up a Slack user by ID or email.";
+        readonly requiredScopes: "users:read,users:read.email";
+    }, {
+        readonly key: "slack-list-channels";
+        readonly title: "List Channels";
+        readonly description: "Browse the channels and DMs the agent can see.";
+        readonly requiredScopes: "channels:read,groups:read,mpim:read,im:read";
+    }, {
+        readonly key: "slack-send-message";
+        readonly title: "Send Message";
+        readonly description: "Post a message to a Slack channel, DM, or thread.";
+        readonly requiredScopes: "chat:write";
+    }, {
+        readonly key: "slack-upload-file";
+        readonly title: "Upload File";
+        readonly description: "Upload a stored resource into a Slack channel.";
+        readonly requiredScopes: "files:write,chat:write";
+    }];
+}, {
+    readonly key: "slack-user";
+    readonly title: "Slack Search";
+    readonly description: "Workspace-wide message search for Slack. Backed by a user (xoxp) token because Slack does not allow bot tokens to call search.messages.";
+    readonly icon: "https://api.iconify.design/logos:slack-icon.svg";
+    readonly provider: "slack-user";
+    readonly tools: readonly [{
+        readonly key: "slack-search-messages";
+        readonly title: "Search Messages";
+        readonly description: "Search messages across the workspace. Requires a Slack user token (xoxp).";
+        readonly requiredScopes: "search:read";
+    }];
+}, {
+    readonly key: "google-calendar";
+    readonly title: "Google Calendar";
+    readonly description: "Create and manage calendar events, and find open time slots";
+    readonly icon: "https://api.iconify.design/logos:google-calendar.svg";
+    readonly provider: "google-calendar";
+    readonly tools: readonly [{
+        readonly key: "calendar-create-event";
+        readonly title: "Create Event";
+        readonly description: "Add a new event to a calendar.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/calendar.events";
+    }, {
+        readonly key: "calendar-delete-event";
+        readonly title: "Delete Event";
+        readonly description: "Permanently remove an event from a calendar.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/calendar.events";
+    }, {
+        readonly key: "calendar-find-free-slots";
+        readonly title: "Find Free Slots";
+        readonly description: "Find open time gaps on a calendar.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/calendar.readonly";
+    }, {
+        readonly key: "calendar-list-calendars";
+        readonly title: "List Calendars";
+        readonly description: "See all calendars on the connected Google account.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/calendar.readonly";
+    }, {
+        readonly key: "calendar-list-events";
+        readonly title: "List Events";
+        readonly description: "Browse events on a calendar within a time range.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/calendar.readonly";
+    }, {
+        readonly key: "calendar-update-event";
+        readonly title: "Update Event";
+        readonly description: "Change the details of an existing event.";
+        readonly requiredScopes: "https://www.googleapis.com/auth/calendar.events";
+    }];
+}, {
+    readonly key: "calcom";
+    readonly title: "Cal.com";
+    readonly description: "Check availability and book or cancel meetings on Cal.com";
+    readonly icon: "https://api.iconify.design/simple-icons:caldotcom.svg";
+    readonly provider: "calcom";
+    readonly tools: readonly [{
+        readonly key: "calcom-cancel-booking";
+        readonly title: "Cancel Booking";
+        readonly description: "Cancel an existing booking by its UID.";
+        readonly requiredScopes: null;
+    }, {
+        readonly key: "calcom-create-booking";
+        readonly title: "Create Booking";
+        readonly description: "Book an available slot for an attendee.";
+        readonly requiredScopes: null;
+    }, {
+        readonly key: "calcom-list-available-slots";
+        readonly title: "List Available Slots";
+        readonly description: "Find open booking times for an event type in a date range.";
+        readonly requiredScopes: null;
+    }, {
+        readonly key: "calcom-list-event-types";
+        readonly title: "List Event Types";
+        readonly description: "See the bookable meeting types on the connected Cal.com account.";
+        readonly requiredScopes: null;
+    }];
+}, {
+    readonly key: "web";
+    readonly title: "Web Search";
+    readonly description: "Search the live web and extract page content, powered by Tavily.";
+    readonly icon: "https://api.iconify.design/mdi:web.svg";
+    readonly provider: "tavily";
+    readonly tools: readonly [{
+        readonly key: "web-extract";
+        readonly title: "Web Extract";
+        readonly description: "Fetch the full cleaned text of specific web pages by URL for in-depth reading.";
+        readonly requiredScopes: null;
+    }, {
+        readonly key: "web-search";
+        readonly title: "Web Search";
+        readonly description: "Search the live web and return the top results plus a synthesized answer so the model can cite sources.";
+        readonly requiredScopes: null;
+    }];
+}, {
+    readonly key: "builtin";
+    readonly title: "Built-in";
+    readonly description: "Core tools available to every MCP server";
+    readonly icon: null;
+    readonly provider: null;
+    readonly tools: readonly [{
+        readonly key: "list-prompts";
+        readonly title: "List Prompts";
+        readonly description: "List the prompts and commands this assistant exposes, and how to run them on the current channel.";
+        readonly requiredScopes: null;
+    }, {
+        readonly key: "list-resources";
+        readonly title: "List Resources";
+        readonly description: "List every resource available to this assistant.";
+        readonly requiredScopes: null;
+    }, {
+        readonly key: "read-resource";
+        readonly title: "Read Resource";
+        readonly description: "Read the contents of a stored resource.";
+        readonly requiredScopes: null;
+    }, {
+        readonly key: "search-resources";
+        readonly title: "Search Resources";
+        readonly description: "Find the resources most relevant to a question using semantic search.";
+        readonly requiredScopes: null;
+    }, {
+        readonly key: "send-resource";
+        readonly title: "Send Resource";
+        readonly description: "Deliver a resource to the user as a chat attachment.";
+        readonly requiredScopes: null;
+    }];
+}, {
+    readonly key: "greeting";
+    readonly title: "Greeting";
+    readonly description: "Simple greeting utilities";
+    readonly icon: null;
+    readonly provider: null;
+    readonly tools: readonly [{
+        readonly key: "greeting";
+        readonly title: "Greeting";
+        readonly description: "Reply with a friendly hello in English or Spanish (demo tool).";
+        readonly requiredScopes: null;
+    }];
+}, {
+    readonly key: "http-endpoint";
+    readonly title: "HTTP Endpoints";
+    readonly description: "Expose your own HTTP APIs to the agent as named tools. Each endpoint you add becomes a tool the assistant can call.";
+    readonly icon: "https://api.iconify.design/mdi:api.svg";
+    readonly provider: null;
+    readonly tools: readonly [{
+        readonly key: "http-endpoint";
+        readonly title: "HTTP Endpoint";
+        readonly description: "A user-configured HTTP request exposed to the agent as its own named tool.";
+        readonly requiredScopes: null;
+    }];
+}, {
+    readonly key: "mcp-proxy";
+    readonly title: "MCP Servers";
+    readonly description: "Connect a vendor's official remote MCP server and expose its tools to the agent. Each server you add brings its own set of tools.";
+    readonly icon: "https://api.iconify.design/mdi:server-network.svg";
+    readonly provider: null;
+    readonly tools: readonly [{
+        readonly key: "mcp-proxy";
+        readonly title: "MCP Server";
+        readonly description: "A connected remote MCP server. Each server you add exposes its tools to the agent under a vendor prefix.";
+        readonly requiredScopes: null;
+    }];
+}, {
+    readonly key: "custom-code";
+    readonly title: "Custom code";
+    readonly description: "Write your own tools as a Cloudflare Worker and deploy them to this MCP server.";
+    readonly icon: null;
+    readonly provider: null;
+    readonly tools: readonly [{
+        readonly key: "custom-code";
+        readonly title: "Custom code";
+        readonly description: "Tools implemented by your own code. One script per artifact; names and schemas come from the published version.";
+        readonly requiredScopes: null;
+    }];
+}];
+export type ToolKey = (typeof TOOL_CATALOG)[number]['tools'][number]['key'];
+export type ToolGroupKey = (typeof TOOL_CATALOG)[number]['key'];
+export declare const TOOL_KEYS: ToolKey[];
+/**
+ * Look up one tool and the group it belongs to.
+ *
+ * Returns undefined rather than throwing, because the callers that matter are
+ * reading a STORED `artifact_tool.tool_key` — a row written before a tool was
+ * retired still has to be readable. The MCP boot loop skips what it can't
+ * resolve; it must never fail the whole artifact over one row.
+ */
+export declare const findCatalogTool: (key: string) => {
+    tool: CatalogTool;
+    group: CatalogGroup;
+} | undefined;
+export declare const findCatalogGroup: (key: string) => CatalogGroup | undefined;
+/**
+ * Is this a tool the platform ships? Used on the WRITE path, where installing an
+ * unknown key has to be refused — unlike the read path above, which is lenient
+ * on purpose.
+ */
+export declare const isToolKey: (key: string) => key is ToolKey;
+/**
+ * One installed tool's catalog entry, shaped for an API response.
+ *
+ * `artifact_tool` rows carry only a key, so every surface that renders a tool —
+ * the dashboard's cards, a channel's usage attribution — needs the title,
+ * description and group that used to arrive on the join. Attaching it
+ * server-side keeps those responses self-describing, so a client never has to
+ * hold its own copy of the catalog to render a row.
+ *
+ * Null for a key the catalog no longer offers. Callers render what they can
+ * (the key is still on the row) rather than dropping the tool.
+ */
+export interface CatalogToolDescriptor {
+    key: string;
+    title: string;
+    description: string | null;
+    requiredScopes: string | null;
+    group: Omit<CatalogGroup, 'tools'>;
+}
+export declare const describeCatalogTool: (key: string) => CatalogToolDescriptor | null;
+//# sourceMappingURL=toolCatalog.d.ts.map

package/dist/toolCatalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolCatalog.d.ts","sourceRoot":"","sources":["../src/toolCatalog.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,WAAW;IAG1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAI3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAGpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CAC/B;AAMD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyfmB,CAAC;AAI7C,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;AAC5E,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;AAgBhE,eAAO,MAAM,SAAS,EAA6B,OAAO,EAAE,CAAC;AAE7D;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAC1B,KAAK,MAAM,KACV;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAAG,SAC3B,CAAC;AAEtB,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,KAAG,YAAY,GAAG,SACxC,CAAC;AAEvB;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,KAAG,GAAG,IAAI,OAA8B,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,eAAO,MAAM,mBAAmB,GAC9B,KAAK,MAAM,KACV,qBAAqB,GAAG,IAiB1B,CAAC"}