@hexclave/shared 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2024 Stackframe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/ai/image-limits.d.ts

@@ -0,0 +1,24 @@
+//#region src/ai/image-limits.d.ts
+/** Shared image attachment limits for AI chat (client composer + `/api/latest/ai/query/[mode]`). */
+declare const MAX_IMAGES_PER_MESSAGE = 3;
+declare const MAX_IMAGE_BYTES_PER_FILE: number;
+declare const MAX_IMAGE_MB_PER_FILE: number;
+/** Decoded byte length of a base64 data URL or raw base64 (padding error ≤ 2 bytes). */
+declare function estimateBase64ByteLength(dataUrl: string): number;
+type ValidationResult = {
+  ok: true;
+} | {
+  ok: false;
+  reason: string;
+};
+type MessageLike = {
+  role?: unknown;
+  content?: unknown;
+};
+declare function validateImageCount(imageCount: number): ValidationResult;
+declare function validateImageByteLength(bytes: number): ValidationResult;
+/** Validates per-message image count and per-file size for user messages. */
+declare function validateImageAttachments(messages: readonly MessageLike[]): ValidationResult;
+//#endregion
+export { MAX_IMAGES_PER_MESSAGE, MAX_IMAGE_BYTES_PER_FILE, MAX_IMAGE_MB_PER_FILE, estimateBase64ByteLength, validateImageAttachments, validateImageByteLength, validateImageCount };
+//# sourceMappingURL=image-limits.d.ts.map

package/dist/ai/image-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-limits.d.ts","names":[],"sources":["../../src/ai/image-limits.ts"],"mappings":";;cAEa,sBAAA;AAAA,cACA,wBAAA;AAAA,cACA,qBAAA;;iBAGG,wBAAA,CAAyB,OAAA;AAAA,KAUpC,gBAAA;EAAqB,EAAA;AAAA;EAAe,EAAA;EAAW,MAAA;AAAA;AAAA,KAE/C,WAAA;EAAgB,IAAA;EAAgB,OAAA;AAAA;AAAA,iBAErB,kBAAA,CAAmB,UAAA,WAAqB,gBAAA;AAAA,iBAUxC,uBAAA,CAAwB,KAAA,WAAgB,gBAAA;;iBAWxC,wBAAA,CAAyB,QAAA,WAAmB,WAAA,KAAgB,gBAAA"}

package/dist/ai/image-limits.js

@@ -0,0 +1,61 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/ai/image-limits.ts
+/** Shared image attachment limits for AI chat (client composer + `/api/latest/ai/query/[mode]`). */
+const MAX_IMAGES_PER_MESSAGE = 3;
+const MAX_IMAGE_BYTES_PER_FILE = 3 * 1024 * 1024;
+const MAX_IMAGE_MB_PER_FILE = MAX_IMAGE_BYTES_PER_FILE / (1024 * 1024);
+/** Decoded byte length of a base64 data URL or raw base64 (padding error ≤ 2 bytes). */
+function estimateBase64ByteLength(dataUrl) {
+	const commaIdx = dataUrl.indexOf(",");
+	const base64 = commaIdx === -1 ? dataUrl : dataUrl.slice(commaIdx + 1);
+	if (base64.length === 0) return 0;
+	let padding = 0;
+	if (base64.endsWith("==")) padding = 2;
+	else if (base64.endsWith("=")) padding = 1;
+	return Math.max(0, Math.floor(base64.length * 3 / 4) - padding);
+}
+function validateImageCount(imageCount) {
+	if (imageCount > MAX_IMAGES_PER_MESSAGE) return {
+		ok: false,
+		reason: `Maximum ${MAX_IMAGES_PER_MESSAGE} images per message.`
+	};
+	return { ok: true };
+}
+function validateImageByteLength(bytes) {
+	if (bytes > MAX_IMAGE_BYTES_PER_FILE) return {
+		ok: false,
+		reason: `Image exceeds ${MAX_IMAGE_MB_PER_FILE}MB limit (${(bytes / 1024 / 1024).toFixed(2)}MB).`
+	};
+	return { ok: true };
+}
+/** Validates per-message image count and per-file size for user messages. */
+function validateImageAttachments(messages) {
+	for (const msg of messages) {
+		if (!Array.isArray(msg.content)) continue;
+		let imageCount = 0;
+		for (const rawPart of msg.content) {
+			if (!rawPart || typeof rawPart !== "object") continue;
+			const part = rawPart;
+			if (part.type !== "image") continue;
+			imageCount++;
+			const countValidation = validateImageCount(imageCount);
+			if (!countValidation.ok) return countValidation;
+			if (typeof part.image === "string") {
+				const sizeValidation = validateImageByteLength(estimateBase64ByteLength(part.image));
+				if (!sizeValidation.ok) return sizeValidation;
+			}
+		}
+	}
+	return { ok: true };
+}
+
+//#endregion
+exports.MAX_IMAGES_PER_MESSAGE = MAX_IMAGES_PER_MESSAGE;
+exports.MAX_IMAGE_BYTES_PER_FILE = MAX_IMAGE_BYTES_PER_FILE;
+exports.MAX_IMAGE_MB_PER_FILE = MAX_IMAGE_MB_PER_FILE;
+exports.estimateBase64ByteLength = estimateBase64ByteLength;
+exports.validateImageAttachments = validateImageAttachments;
+exports.validateImageByteLength = validateImageByteLength;
+exports.validateImageCount = validateImageCount;
+//# sourceMappingURL=image-limits.js.map

package/dist/ai/image-limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-limits.js","names":[],"sources":["../../src/ai/image-limits.ts"],"sourcesContent":["/** Shared image attachment limits for AI chat (client composer + `/api/latest/ai/query/[mode]`). */\n\nexport const MAX_IMAGES_PER_MESSAGE = 3;\nexport const MAX_IMAGE_BYTES_PER_FILE = 3 * 1024 * 1024;\nexport const MAX_IMAGE_MB_PER_FILE = MAX_IMAGE_BYTES_PER_FILE / (1024 * 1024);\n\n/** Decoded byte length of a base64 data URL or raw base64 (padding error ≤ 2 bytes). */\nexport function estimateBase64ByteLength(dataUrl: string): number {\n  const commaIdx = dataUrl.indexOf(\",\");\n  const base64 = commaIdx === -1 ? dataUrl : dataUrl.slice(commaIdx + 1);\n  if (base64.length === 0) return 0;\n  let padding = 0;\n  if (base64.endsWith(\"==\")) padding = 2;\n  else if (base64.endsWith(\"=\")) padding = 1;\n  return Math.max(0, Math.floor((base64.length * 3) / 4) - padding);\n}\n\ntype ValidationResult = { ok: true } | { ok: false, reason: string };\ntype UnknownPart = { type?: unknown, image?: unknown };\ntype MessageLike = { role?: unknown, content?: unknown };\n\nexport function validateImageCount(imageCount: number): ValidationResult {\n  if (imageCount > MAX_IMAGES_PER_MESSAGE) {\n    return {\n      ok: false,\n      reason: `Maximum ${MAX_IMAGES_PER_MESSAGE} images per message.`,\n    };\n  }\n  return { ok: true };\n}\n\nexport function validateImageByteLength(bytes: number): ValidationResult {\n  if (bytes > MAX_IMAGE_BYTES_PER_FILE) {\n    return {\n      ok: false,\n      reason: `Image exceeds ${MAX_IMAGE_MB_PER_FILE}MB limit (${(bytes / 1024 / 1024).toFixed(2)}MB).`,\n    };\n  }\n  return { ok: true };\n}\n\n/** Validates per-message image count and per-file size for user messages. */\nexport function validateImageAttachments(messages: readonly MessageLike[]): ValidationResult {\n  for (const msg of messages) {\n    if (!Array.isArray(msg.content)) continue;\n    let imageCount = 0;\n    for (const rawPart of msg.content as unknown[]) {\n      if (!rawPart || typeof rawPart !== \"object\") continue;\n      const part = rawPart as UnknownPart;\n      if (part.type !== \"image\") continue;\n      imageCount++;\n      const countValidation = validateImageCount(imageCount);\n      if (!countValidation.ok) return countValidation;\n      if (typeof part.image === \"string\") {\n        const bytes = estimateBase64ByteLength(part.image);\n        const sizeValidation = validateImageByteLength(bytes);\n        if (!sizeValidation.ok) return sizeValidation;\n      }\n    }\n  }\n  return { ok: true };\n}\n"],"mappings":";;;;AAEA,MAAa,yBAAyB;AACtC,MAAa,2BAA2B,IAAI,OAAO;AACnD,MAAa,wBAAwB,4BAA4B,OAAO;;AAGxE,SAAgB,yBAAyB,SAAyB;CAChE,MAAM,WAAW,QAAQ,QAAQ,IAAI;CACrC,MAAM,SAAS,aAAa,KAAK,UAAU,QAAQ,MAAM,WAAW,EAAE;AACtE,KAAI,OAAO,WAAW,EAAG,QAAO;CAChC,IAAI,UAAU;AACd,KAAI,OAAO,SAAS,KAAK,CAAE,WAAU;UAC5B,OAAO,SAAS,IAAI,CAAE,WAAU;AACzC,QAAO,KAAK,IAAI,GAAG,KAAK,MAAO,OAAO,SAAS,IAAK,EAAE,GAAG,QAAQ;;AAOnE,SAAgB,mBAAmB,YAAsC;AACvE,KAAI,aAAa,uBACf,QAAO;EACL,IAAI;EACJ,QAAQ,WAAW,uBAAuB;EAC3C;AAEH,QAAO,EAAE,IAAI,MAAM;;AAGrB,SAAgB,wBAAwB,OAAiC;AACvE,KAAI,QAAQ,yBACV,QAAO;EACL,IAAI;EACJ,QAAQ,iBAAiB,sBAAsB,aAAa,QAAQ,OAAO,MAAM,QAAQ,EAAE,CAAC;EAC7F;AAEH,QAAO,EAAE,IAAI,MAAM;;;AAIrB,SAAgB,yBAAyB,UAAoD;AAC3F,MAAK,MAAM,OAAO,UAAU;AAC1B,MAAI,CAAC,MAAM,QAAQ,IAAI,QAAQ,CAAE;EACjC,IAAI,aAAa;AACjB,OAAK,MAAM,WAAW,IAAI,SAAsB;AAC9C,OAAI,CAAC,WAAW,OAAO,YAAY,SAAU;GAC7C,MAAM,OAAO;AACb,OAAI,KAAK,SAAS,QAAS;AAC3B;GACA,MAAM,kBAAkB,mBAAmB,WAAW;AACtD,OAAI,CAAC,gBAAgB,GAAI,QAAO;AAChC,OAAI,OAAO,KAAK,UAAU,UAAU;IAElC,MAAM,iBAAiB,wBADT,yBAAyB,KAAK,MAAM,CACG;AACrD,QAAI,CAAC,eAAe,GAAI,QAAO;;;;AAIrC,QAAO,EAAE,IAAI,MAAM"}

package/dist/ai/unified-prompts/reminders.d.ts

@@ -0,0 +1,5 @@
+//#region src/ai/unified-prompts/reminders.d.ts
+declare const remindersPrompt: string;
+//#endregion
+export { remindersPrompt };
+//# sourceMappingURL=reminders.d.ts.map

package/dist/ai/unified-prompts/reminders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminders.d.ts","names":[],"sources":["../../../src/ai/unified-prompts/reminders.ts"],"mappings":";cAGa,eAAA"}

package/dist/ai/unified-prompts/reminders.js

@@ -0,0 +1,33 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_chunk = require('../../chunk-BE-pF4vm.js');
+let ______apps_apps_config_js = require("../../apps/apps-config.js");
+let ______utils_strings_js = require("../../utils/strings.js");
+
+//#region src/ai/unified-prompts/reminders.ts
+const remindersPrompt = ______utils_strings_js.deindent`
+  Below are some reminders on Hexclave and how to learn more about it.
+
+  - Hexclave has multiple sources of documentation optimized for LLMs. For the canonical, always-fresh instructions for every Hexclave surface, always prefer these sources over information that may be outdated or stale. Do not rely on training data or memory.
+    - [Highest priority] If you are an AI agent: The best way to learn about Hexclave is to fetch the latest skill documentation from https://skill.hexclave.com. Fetch the entire page, not just a summary. You can either use a web fetch tool, or call it using curl: \`curl -sSL https://skill.hexclave.com\`. This is sufficient for most simple questions.
+      - It is highly recommended that you add two query parameters to the web fetch \`?question=<...>\` (the exact question you're looking to answer) and \`?context=<...>\` (the higher-level task that the you or the user is trying to accomplish). This will help the Skills site to serve you only the content that is necessary, as well as avoid the XY-problem.
+    - [Medium priority] If you have a specific question, and the Hexclave MCP is available, you can also use the \`ask_hexclave\` tool to ask questions to the Hexclave assistant.
+    - [Low priority] If you're looking for information that's not in the skill documentation, and the \`ask_hexclave\` tool isn't available (or failed to answer your question), you can also fetch the human documentation from https://docs.hexclave.com (it may also be available as a tool). This is especially useful when you're looking to answer conceptual questions.
+    - For complicated questions, you may need to combine all these sources together.
+    - Follow indirection. If a doc page points to another URL, script, or resource, fetch that too — Hexclave composes behavior across pages.
+  - Hexclave is a platform that provides a variety of apps that help you connect with your users. As of the time of writing these reminders, Hexclave provides the following apps (although not all may be enabled): ${Object.entries(______apps_apps_config_js.ALL_APPS).filter(([, app]) => app.stage !== "alpha").map(([key]) => key).join(", ")}. Don't hardcode this list, as it changes rapidly.
+  - The most important object in Hexclave is the Hexclave App object. HexclaveClientApp provides client-side functionality, while HexclaveServerApp also provides server-side functionality (but can usually only be imported on the server, as it requires a secret server key environment variable). You can usually find an instance of this object in a file called \`hexclave/client.tsx\` or \`hexclave/server.tsx\`, although it may be in a different location in this particular codebase.
+  - Take extra care to always have great error handling and loading states whenever necessary (including in button onClick handlers; Hexclave's code examples often use a special onClick class which handles loading states, but your own button may not). Hexclave's SDK tends to return errors that need to be handled explicitly in its return types.
+  - Language, framework, and library-specific details:
+    - JavaScript & TypeScript:
+      - Hexclave has different SDK packages for different frameworks and languages. As of the time of writing these reminders, they are: @hexclave/js (JavaScript/TypeScript), @hexclave/stack (Next.js), @hexclave/react (React), @hexclave/tanstack-start (TanStack Start). You can find all of these on npm. They are all versioned together, meaning that vX.Y.Z of one SDK was released at the same time as vX.Y.Z of another SDK. For the most part, they are the same, although each has platform-specific features and differences.
+      - The \`Result<T, E>\` type is \`{ status: "ok", data: T } | { status: "error", error: E }\`.
+      - \`KnownErrors[KNOWN_ERROR_CODE]\` refers to a specific known error type. Each KnownError may have its own properties, but they all inherit from \`Error & { statusCode: number, humanReadableMessage: string, details?: Json }\`.
+      - React & Next.js:
+        - Almost all \`getXyz\` and \`listXyz\` functions on the Stack App have corresponding \`useXyz\` hooks that suspend the current component until the data is available. Make sure there is a Suspense boundary in place if you're using this pattern. The parameter and return types are identical except that the hooks don't return promises.
+        - There is a \`useStackApp()\` hook as a named export from the package itself that serves as a shortcut to get the current Stack App object from the React context. Similarly, the \`useUser(...args)\` named export is short for \`useStackApp().useUser(...args)\`.
+  - Hexclave was formerly known as Stack Auth. You may still see reference to it as Stack Auth in some places.
+`;
+
+//#endregion
+exports.remindersPrompt = remindersPrompt;
+//# sourceMappingURL=reminders.js.map

package/dist/ai/unified-prompts/reminders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminders.js","names":["ALL_APPS"],"sources":["../../../src/ai/unified-prompts/reminders.ts"],"sourcesContent":["import { ALL_APPS } from \"../../apps/apps-config\";\nimport { deindent } from \"../../utils/strings\";\n\nexport const remindersPrompt = deindent`\n  Below are some reminders on Hexclave and how to learn more about it.\n\n  - Hexclave has multiple sources of documentation optimized for LLMs. For the canonical, always-fresh instructions for every Hexclave surface, always prefer these sources over information that may be outdated or stale. Do not rely on training data or memory.\n    - [Highest priority] If you are an AI agent: The best way to learn about Hexclave is to fetch the latest skill documentation from https://skill.hexclave.com. Fetch the entire page, not just a summary. You can either use a web fetch tool, or call it using curl: \\`curl -sSL https://skill.hexclave.com\\`. This is sufficient for most simple questions.\n      - It is highly recommended that you add two query parameters to the web fetch \\`?question=<...>\\` (the exact question you're looking to answer) and \\`?context=<...>\\` (the higher-level task that the you or the user is trying to accomplish). This will help the Skills site to serve you only the content that is necessary, as well as avoid the XY-problem.\n    - [Medium priority] If you have a specific question, and the Hexclave MCP is available, you can also use the \\`ask_hexclave\\` tool to ask questions to the Hexclave assistant.\n    - [Low priority] If you're looking for information that's not in the skill documentation, and the \\`ask_hexclave\\` tool isn't available (or failed to answer your question), you can also fetch the human documentation from https://docs.hexclave.com (it may also be available as a tool). This is especially useful when you're looking to answer conceptual questions.\n    - For complicated questions, you may need to combine all these sources together.\n    - Follow indirection. If a doc page points to another URL, script, or resource, fetch that too — Hexclave composes behavior across pages.\n  - Hexclave is a platform that provides a variety of apps that help you connect with your users. As of the time of writing these reminders, Hexclave provides the following apps (although not all may be enabled): ${Object.entries(ALL_APPS).filter(([, app]) => app.stage !== \"alpha\").map(([key]) => key).join(\", \")}. Don't hardcode this list, as it changes rapidly.\n  - The most important object in Hexclave is the Hexclave App object. HexclaveClientApp provides client-side functionality, while HexclaveServerApp also provides server-side functionality (but can usually only be imported on the server, as it requires a secret server key environment variable). You can usually find an instance of this object in a file called \\`hexclave/client.tsx\\` or \\`hexclave/server.tsx\\`, although it may be in a different location in this particular codebase.\n  - Take extra care to always have great error handling and loading states whenever necessary (including in button onClick handlers; Hexclave's code examples often use a special onClick class which handles loading states, but your own button may not). Hexclave's SDK tends to return errors that need to be handled explicitly in its return types.\n  - Language, framework, and library-specific details:\n    - JavaScript & TypeScript:\n      - Hexclave has different SDK packages for different frameworks and languages. As of the time of writing these reminders, they are: @hexclave/js (JavaScript/TypeScript), @hexclave/stack (Next.js), @hexclave/react (React), @hexclave/tanstack-start (TanStack Start). You can find all of these on npm. They are all versioned together, meaning that vX.Y.Z of one SDK was released at the same time as vX.Y.Z of another SDK. For the most part, they are the same, although each has platform-specific features and differences.\n      - The \\`Result<T, E>\\` type is \\`{ status: \"ok\", data: T } | { status: \"error\", error: E }\\`.\n      - \\`KnownErrors[KNOWN_ERROR_CODE]\\` refers to a specific known error type. Each KnownError may have its own properties, but they all inherit from \\`Error & { statusCode: number, humanReadableMessage: string, details?: Json }\\`.\n      - React & Next.js:\n        - Almost all \\`getXyz\\` and \\`listXyz\\` functions on the Stack App have corresponding \\`useXyz\\` hooks that suspend the current component until the data is available. Make sure there is a Suspense boundary in place if you're using this pattern. The parameter and return types are identical except that the hooks don't return promises.\n        - There is a \\`useStackApp()\\` hook as a named export from the package itself that serves as a shortcut to get the current Stack App object from the React context. Similarly, the \\`useUser(...args)\\` named export is short for \\`useStackApp().useUser(...args)\\`.\n  - Hexclave was formerly known as Stack Auth. You may still see reference to it as Stack Auth in some places.\n`;\n"],"mappings":";;;;;;AAGA,MAAa,kBAAkB,+BAAQ;;;;;;;;;;uNAUgL,OAAO,QAAQA,mCAAS,CAAC,QAAQ,GAAG,SAAS,IAAI,UAAU,QAAQ,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,KAAK,KAAK,CAAC"}

package/dist/ai/unified-prompts/skill-site-prompt-parts/ai-setup-prompt.d.ts

@@ -0,0 +1,11 @@
+//#region src/ai/unified-prompts/skill-site-prompt-parts/ai-setup-prompt.d.ts
+declare const convexSetupPrompt: string;
+declare const supabaseSetupPrompt: string;
+declare const cliSetupPrompt: string;
+declare const aiAgentConfigPreparationPrompt: string;
+declare const prodReadyPrompt: string;
+declare function getSdkSetupPrompt(mainType: "ai-prompt" | "nextjs" | "react" | "js" | "tanstack-start" | "nodejs" | "bun"): string;
+declare const aiSetupPrompt: string;
+//#endregion
+export { aiAgentConfigPreparationPrompt, aiSetupPrompt, cliSetupPrompt, convexSetupPrompt, getSdkSetupPrompt, prodReadyPrompt, supabaseSetupPrompt };
+//# sourceMappingURL=ai-setup-prompt.d.ts.map

package/dist/ai/unified-prompts/skill-site-prompt-parts/ai-setup-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-setup-prompt.d.ts","names":[],"sources":["../../../../src/ai/unified-prompts/skill-site-prompt-parts/ai-setup-prompt.ts"],"mappings":";cAEa,iBAAA;AAAA,cA6FA,mBAAA;AAAA,cAmKA,cAAA;AAAA,cA6EA,8BAAA;AAAA,cAkCA,eAAA;AAAA,iBAIG,iBAAA,CAAkB,QAAA;AAAA,cAucrB,aAAA"}