@hybrd/utils 0.7.6 → 1.0.1

package/src/lib/cloudflare.ts

@@ -0,0 +1,74 @@
+/**
+ * Cloudflare environment detection and storage utilities
+ */
+
+declare const process: {
+  env: Record<string, string | undefined>
+  cwd(): string
+}
+
+export interface CloudflareEnvironment {
+  isCloudflare: boolean
+  platform: 'pages' | 'workers' | 'local'
+  storagePath: string
+}
+
+/**
+ * Detects if running in Cloudflare environment and returns appropriate storage configuration
+ */
+export function getCloudflareEnvironment(): CloudflareEnvironment {
+  if (process.env.CF_PAGES_BRANCH) {
+    return {
+      isCloudflare: true,
+      platform: 'pages',
+      storagePath: '/tmp'
+    }
+  }
+
+  if (process.env.CF_WORKER_NAME) {
+    return {
+      isCloudflare: true,
+      platform: 'workers',
+      storagePath: '/tmp'
+    }
+  }
+
+  return {
+    isCloudflare: false,
+    platform: 'local',
+    storagePath: process.env.PROJECT_ROOT || process.cwd()
+  }
+}
+
+/**
+ * Gets the appropriate storage path for the current environment
+ * @param subPath - Optional subdirectory within the storage path
+ */
+export function getCloudflareStoragePath(subPath?: string): string {
+  const env = getCloudflareEnvironment()
+  
+  if (env.isCloudflare) {
+    return subPath ? `/tmp/${subPath}` : '/tmp'
+  }
+
+  const basePath = env.storagePath
+  const dataPath = subPath ? `${basePath}/.data/${subPath}` : `${basePath}/.data`
+  
+  return dataPath
+}
+
+/**
+ * Gets service URL based on Cloudflare environment variables
+ */
+export function getCloudflareServiceUrl(fallbackPort = 3000): string {
+  if (process.env.CF_PAGES_URL) {
+    return process.env.CF_PAGES_URL
+  }
+
+  if (process.env.CF_WORKER_URL) {
+    return process.env.CF_WORKER_URL
+  }
+
+  // Local development fallback
+  return `http://localhost:${fallbackPort}`
+}

package/src/lib/date.ts

@@ -0,0 +1,40 @@
+import { format, isToday, isYesterday } from "date-fns";
+
+/**
+ * Formats a date string or Date object into a localized date string
+ * @param stringOrDate - Date string or Date object to format
+ * @returns Formatted date string (e.g., "Jan 1, 2024") or empty string if no input
+ */
+export function formatDate(stringOrDate?: string | Date): string {
+	if (!stringOrDate) return "";
+
+	const date = new Date(stringOrDate);
+
+	return date.toLocaleDateString(undefined, {
+		year: "numeric",
+		month: "short",
+		day: "numeric",
+	});
+}
+
+/**
+ * Formats a date relative to the current time
+ * @param date - Date object to format
+ * @returns Formatted string with relative time:
+ * - "Today, [time]" for today's dates
+ * - "Yesterday, [time]" for yesterday's dates
+ * - "MMM d, h:mm a" for dates in current year
+ * - "MMM d, yyyy" for dates in other years
+ */
+export function formatRelativeDate(date: Date) {
+	if (isToday(date)) {
+		return `Today, ${format(date, "h:mm a")}`;
+	}
+	if (isYesterday(date)) {
+		return `Yesterday, ${format(date, "h:mm a")}`;
+	}
+	if (new Date().getFullYear() === date.getFullYear()) {
+		return format(date, "MMM d, h:mm a");
+	}
+	return format(date, "MMM d, yyyy");
+}

package/src/lib/markdown.ts

@@ -0,0 +1,12 @@
+import { remark } from "remark"
+import strip from "strip-markdown"
+
+/**
+ * Strips markdown from a string
+ * @param markdown - The markdown string to strip
+ * @returns The stripped markdown string
+ */
+export async function stripMarkdown(markdown: string) {
+	const file = await remark().use(strip).process(markdown)
+	return String(file)
+}

package/src/lib/object.ts

@@ -0,0 +1,54 @@
+/**
+ * Stringifies all values in an object, including objects and null values.
+ * If obj is undefined, returns an empty object.
+ * @param obj - The object to stringify
+ * @returns A new object with the same keys as obj, but with all values stringified
+ */
+export function stringifyValues(
+	obj: Record<string, unknown> | undefined
+): Record<string, string> {
+	const result: Record<string, string> = {}
+
+	if (!obj) {
+		return {}
+	}
+
+	for (const key in obj) {
+		const value = obj[key]
+		result[key] =
+			value === null
+				? "null"
+				: typeof value === "object"
+					? JSON.stringify(value)
+					: String(value)
+	}
+
+	return result
+}
+
+/**
+ * Removes empty values (undefined, null, empty strings) from an object
+ *
+ * @param obj - The object to prune
+ * @returns A new object with empty values removed
+ */
+export function pruneEmpty<T extends Record<string, unknown>>(
+	obj: T | undefined
+): Partial<T> {
+	if (!obj) {
+		return {}
+	}
+
+	return Object.entries(obj).reduce(
+		(acc, [key, value]) => {
+			// Skip undefined, null, and empty strings
+			if (value === undefined || value === null || value === "") {
+				return acc
+			}
+			// Avoid spread syntax on accumulator
+			acc[key as keyof T] = value as any
+			return acc
+		},
+		{} as Partial<T>
+	)
+}

package/src/lib/storage.ts

@@ -0,0 +1,64 @@
+import fs from "node:fs/promises"
+
+export interface StorageAdapter {
+  uploadFile(localPath: string, remotePath: string): Promise<void>
+  downloadFile(remotePath: string, localPath: string): Promise<void>
+  exists(remotePath: string): Promise<boolean>
+  delete(remotePath: string): Promise<void>
+}
+
+export class R2StorageAdapter implements StorageAdapter {
+  constructor(private bucket: any) {}
+  
+  async uploadFile(localPath: string, remotePath: string): Promise<void> {
+    const fileData = await fs.readFile(localPath)
+    await this.bucket.put(remotePath, fileData)
+  }
+  
+  async downloadFile(remotePath: string, localPath: string): Promise<void> {
+    const object = await this.bucket.get(remotePath)
+    if (object) {
+      await fs.writeFile(localPath, await object.arrayBuffer())
+    }
+  }
+  
+  async exists(remotePath: string): Promise<boolean> {
+    const object = await this.bucket.head(remotePath)
+    return object !== null
+  }
+  
+  async delete(remotePath: string): Promise<void> {
+    await this.bucket.delete(remotePath)
+  }
+}
+
+export class ExternalDatabaseAdapter implements StorageAdapter {
+  constructor(private connectionString: string) {}
+  
+  async uploadFile(localPath: string, remotePath: string): Promise<void> {
+    throw new Error('External database storage not yet implemented')
+  }
+  
+  async downloadFile(remotePath: string, localPath: string): Promise<void> {
+    throw new Error('External database storage not yet implemented')
+  }
+  
+  async exists(remotePath: string): Promise<boolean> {
+    return false
+  }
+  
+  async delete(remotePath: string): Promise<void> {
+  }
+}
+
+export function createStorageAdapter(): StorageAdapter | null {
+  if (typeof globalThis !== 'undefined' && 'XMTP_STORAGE' in globalThis) {
+    return new R2StorageAdapter((globalThis as any).XMTP_STORAGE)
+  }
+  
+  if (typeof process !== 'undefined' && process.env?.DATABASE_URL) {
+    return new ExternalDatabaseAdapter(process.env.DATABASE_URL)
+  }
+  
+  return null
+}

package/src/lib/string.ts

@@ -0,0 +1,12 @@
+/**
+ * Truncates a given string to a specified length, adding an ellipsis if the
+ * string is longer than the specified length.
+ *
+ * @param {string} str - The string to truncate.
+ * @param {number} length - The maximum length of the resulting string.
+ *
+ * @returns {string} The truncated string.
+ */
+export function truncate(str: string, length: number) {
+	return str.length > length ? `${str.slice(0, length)}...` : str
+}

package/src/lib/urls.ts

@@ -0,0 +1,39 @@
+/**
+ * Get the agent application URL for webhooks and callbacks
+ *
+ * This function constructs the URL for the main agent application, used primarily
+ * for QStash webhooks and external callbacks. It supports multiple deployment
+ * environments with fallback logic.
+ *
+ * @param path - Optional path to append to the base URL (leading slashes are normalized)
+ * @returns The complete URL for the agent application
+ *
+ * @example
+ * ```typescript
+ * // Get base URL
+ * getUrl() // "http://localhost:8454/"
+ *
+ * // Get URL with path
+ * getUrl("/qstash/webhook") // "http://localhost:8454/qstash/webhook"
+ * getUrl("api/health") // "http://localhost:8454/api/health"
+ * ```
+ *
+ * @remarks
+ * URL resolution priority:
+ * 1. `AGENT_URL` environment variable (custom deployment)
+ * 2. `RAILWAY_PUBLIC_DOMAIN` environment variable (Railway deployment)
+ * 3. `http://localhost:8454/` (default)
+ */
+export function getUrl(path = "") {
+	const trimmedPath = path.replace(/^\/+/, "")
+
+	if (process.env.AGENT_URL) {
+		return `https://${process.env.AGENT_URL}/${trimmedPath}`
+	}
+
+	if (process.env.RAILWAY_PUBLIC_DOMAIN) {
+		return `https://${process.env.RAILWAY_PUBLIC_DOMAIN}/${trimmedPath}`
+	}
+
+	return `https://localhost:8454/${trimmedPath}`
+}

package/src/lib/uuid.ts

@@ -0,0 +1,7 @@
+import { v4 as uuidv4 } from "uuid";
+
+// The node:crypto version is not supported in the browser.
+// Use the uuid package instead.
+export function randomUUID(): string {
+	return uuidv4();
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+	"extends": "@hybrd/tsconfig/internal-package.json",
+	"compilerOptions": {
+		"emitDeclarationOnly": false,
+		"outDir": "dist"
+	},
+	"include": ["src/**/*.ts", "src/**/*.tsx"],
+	"exclude": ["node_modules"]
+}

package/LICENSE.md

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) [2023] [Hybrid INC]
-
-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/README.md

@@ -1,21 +0,0 @@
-# @hybrd/utils
-
-Solidity + TypeScript Framework for rapid Web3 development.
-
-## Documentation
-
-For full documentation and examples, visit [hybrid.dev](https://hybrid.dev).
-
-## Installation
-
-```sh
-npm install hybrid
-```
-
-## Community
-
-Check out the following places for more wagmi-related content:
-
-- Join the discussions on [Discord](https://discord.gg/AcJFXZ9Mfk)
-- Follow [@hybrid\_\_dev](https://twitter.com/hybrid__dev) on Twitter for project updates
-- Contribute or fork on [GitHub](https://github.com/hybridhq/hybrid)