insforge

InsForge App Integration Skill

此技能涵蓋使用 @insforge/sdk 的客戶端 SDK 整合。對於後端基礎設施操作（建立資料表、檢查 schema、部署函式、機密、管理儲存桶、設定付款供應商金鑰/目錄、網站部署、cron 任務與排程、日誌等），請使用 insforge-cli 技能。

快速設定

1. 安裝 SDK

npm install @insforge/sdk@latest

2. 設定環境變數

使用 SDK 前，在專案根目錄建立 .env 檔案（Next.js 使用 .env.local），填入 InsForge URL 和匿名金鑰。

如何取得 URL 和匿名金鑰

1. 確保專案已連結。 檢查專案根目錄是否有 .insforge/project.json。

   • 若為現有專案，執行 npx @insforge/cli link 產生；若為新專案，執行 npx @insforge/cli create。

2. 透過 CLI 取得匿名金鑰：

   npx @insforge/cli secrets get ANON_KEY
   

3. 從 .insforge/project.json 的 oss_host 欄位取得 URL（例如 https://myapp.us-east.insforge.app）。

4. 將兩個值寫入 .env 檔案，使用正確的框架前綴（見下表）。

重要： 對於使用者範圍的 SDK 客戶端（包括 SSR），請使用匿名金鑰。對於需要管理員/服務存取權限的特權伺服器端應用程式碼，請使用 createAdminClient({ apiKey })；API 金鑰是完整存取的管理員金鑰，等同於其他平台的服務角色金鑰。

根據您的框架使用正確的環境變數前綴和存取模式：

框架	.env 檔案	變數	存取模式
Next.js	.env.local	NEXT_PUBLIC_INSFORGE_URL, NEXT_PUBLIC_INSFORGE_ANON_KEY	process.env.NEXT_PUBLIC_*
Vite (React, Vue, Svelte)	.env	VITE_INSFORGE_URL, VITE_INSFORGE_ANON_KEY	import.meta.env.VITE_*
Astro	.env	PUBLIC_INSFORGE_URL, PUBLIC_INSFORGE_ANON_KEY	import.meta.env.PUBLIC_*
SvelteKit	.env	PUBLIC_INSFORGE_URL, PUBLIC_INSFORGE_ANON_KEY	import { env } from '$env/dynamic/public'
Create React App	.env	REACT_APP_INSFORGE_URL, REACT_APP_INSFORGE_ANON_KEY	process.env.REACT_APP_*
Node.js / Server	.env	INSFORGE_URL, INSFORGE_ANON_KEY	process.env.*

Next.js 的 .env.local 範例：

NEXT_PUBLIC_INSFORGE_URL=https://your-appkey.us-east.insforge.app
NEXT_PUBLIC_INSFORGE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...

重要： 將 .env 檔案保留在本機。將 .env、.env.local 和 .env*.local 加入 .gitignore，並保留 .env.example 以記錄必要的變數。

3. 初始化客戶端

Next.js：

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: process.env.NEXT_PUBLIC_INSFORGE_URL,
  anonKey: process.env.NEXT_PUBLIC_INSFORGE_ANON_KEY
})

Vite：

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: import.meta.env.VITE_INSFORGE_URL,
  anonKey: import.meta.env.VITE_INSFORGE_ANON_KEY
})

Astro：

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: import.meta.env.PUBLIC_INSFORGE_URL,
  anonKey: import.meta.env.PUBLIC_INSFORGE_ANON_KEY
})

對於需要專案管理員存取權限的可信任伺服器端程式碼：

import { createAdminClient } from "@insforge/sdk";

const admin = createAdminClient({
  baseUrl: process.env.INSFORGE_URL,
  apiKey: process.env.INSFORGE_API_KEY,
});

模組參考

模組	整合指南
資料庫	database/sdk-integration.md
驗證	auth/sdk-integration.md
儲存	storage/sdk-integration.md
函式	functions/sdk-integration.md
AI	ai/overview.md
即時通訊	realtime/sdk-integration.md
電子郵件	email/sdk-integration.md
付款：Stripe	payments/stripe.md
付款：Razorpay	payments/razorpay.md

各模組涵蓋內容

模組	內容
資料庫	CRUD 操作、篩選、分頁、RPC 呼叫
驗證	註冊/登入、OAuth、工作階段、個人資料、密碼重設
儲存	上傳、下載、刪除檔案；用於 CI/備份工具的 S3 相容閘道；為儲存桶撰寫 RLS 政策
函式	呼叫邊緣函式
AI	透過 OpenRouter 進行聊天、圖片、影片、音訊、嵌入和模型探索的 AI 呼叫
電子郵件	傳送自訂交易式 HTML 電子郵件（歡迎信、電子報、通知）
付款：Stripe	Stripe Checkout 工作階段、訂閱和計費入口重新導向
付款：Razorpay	Razorpay 訂單、訂閱、Checkout.js 和訂閱管理
即時通訊	連線、訂閱、發布事件，以及追蹤在線快照和加入/離開差異

指南

指南	使用時機
../insforge-cli/references/database/access-control.md	應用程式資料表存取控制的後端設定 — 涵蓋 RLS、無限遞迴預防、SECURITY DEFINER 模式、效能提示和常見 InsForge 模式
storage/s3-gateway.md	當使用者是現有 S3 工具（aws CLI、AWS SDK、rclone、Terraform、boto3）且採用 @insforge/sdk 不切實際時的備用路徑 — 涵蓋端點/區域設定、存取金鑰管理、路徑樣式定址以及支援/不支援的 S3 操作。需要 InsForge 2.0.9+。 應用程式碼建議使用 SDK (storage/sdk-integration.md)
storage/postgres-rls.md	為 storage.objects 撰寫 RLS 政策 — 僅擁有者、公開讀取、路徑範圍、團隊共享，以及混合 REST + S3 儲存桶的 NULL uploaded_by 注意事項
../insforge-cli/references/database/vector.md	語意搜尋、推薦或 RAG 的後端設定 — 涵蓋 vector 擴充、schema/維度、距離運算子、HNSW/IVFFlat 索引和 RPC 相似度搜尋
ai/chat-completions.md	透過 OpenRouter 進行文字生成、結構化回答和串流聊天
ai/image-generation.md	透過 OpenRouter 進行圖片生成/編輯，然後持久儲存至 InsForge Storage
ai/video-generation.md	非同步 OpenRouter 影片任務、狀態輪詢和儲存生成的媒體
ai/audio.md	語音轉文字、文字轉語音，以及使用 InsForge 儲存音訊資產/逐字稿
ai/embeddings-and-rag.md	透過 OpenRouter 生成嵌入、儲存至 pgvector，並建立基本 RAG 管線
ai/models-list.md	探索 OpenRouter 模型 ID、模態、參數、定價和嵌入維度
payments	在應用程式整合前設定 Stripe/Razorpay 金鑰、同步供應商目錄、設定 webhook 和撰寫付款 RLS

為新應用程式建立付款功能

首先選擇供應商。沒有通用的應用程式付款指南：

• 對於 Stripe Checkout、訂閱和計費入口，載入 payments/stripe.md。
• 對於 Razorpay 訂單、訂閱、Checkout.js 和取消/暫停/恢復流程，載入 payments/razorpay.md。

在撰寫應用程式碼之前，請使用 insforge-cli 付款參考檢查供應商設定：

npx @insforge/cli payments stripe status
npx @insforge/cli payments razorpay status

如果所選供應商尚未設定，請要求開發者/管理員先設定該供應商。

即時通訊後端設定

即時通訊 SDK 用於前端事件處理和訊息傳遞。使用 insforge-cli 技能設定頻道模式、資料庫觸發器和頻道/訊息 RLS；請參閱 realtime。

後端設定

支援的專案設定選項透過 CLI 管理 — 使用
npx @insforge/cli config export/plan/apply 進行驗證重新導向 URL、
驗證旗標、密碼政策、驗證 SMTP 設定、儲存上傳大小、
即時通訊/排程保留和雲端部署子網域。OAuth 供應商、
外部應用程式設定、儲存桶、函式、機密和部署環境變數
仍使用專用儀表板或 CLI 流程。請參閱 insforge-cli
技能的設定章節。

有風險的後端變更？先使用分支

當此技能中的程式碼變更依賴於 schema 遷移、新的 RLS 政策、OAuth 供應商設定變更 或任何其他影響生產行為的後端變更時，請先建立後端分支。分支共享 JWT_SECRET（現有使用者的 JWT 仍可運作），但會獲得全新的資料庫 + EC2 + API_KEY / ANON_KEY，因此您可以隔離地端到端測試 SDK + 後端變更。

完整的分支工作流程位於 insforge-cli 技能中 — 請參閱 branch 以取得決策指南和生命週期指令。典型循環：

npx @insforge/cli branch create feat-x --mode schema-only
# ... 在分支上套用遷移 / 變更驗證設定 / 更新 RLS ...
# ... 針對分支後端測試 SDK ...
npx @insforge/cli branch merge feat-x --dry-run     # 檢視 SQL
npx @insforge/cli branch merge feat-x               # 套用至父分支

⚠ 在 branch create 或 branch switch 之後，更新應用程式的 InsForge URL 和匿名金鑰環境變數，然後重新啟動您的開發伺服器（或重新載入 .env），以便 SDK 與所選分支後端通訊。

SDK 快速參考

所有 SDK 方法回傳 { data, error }。

模組	方法
insforge.database	.from().select(), .insert(), .update(), .delete(), .rpc()
insforge.auth	.signUp(), .signInWithPassword(), .signInWithOAuth(), .signOut(), .getCurrentUser()
insforge.storage	.from().upload(), .uploadAuto(), .download(), .remove()
insforge.functions	.invoke()
insforge.ai	僅限已棄用的備用：.chat.completions.create(), .images.generate(), .embeddings.create()
insforge.realtime	.connect(), .subscribe(), .publish(), .on(), .disconnect()
insforge.emails	.send({ to, subject, html, cc?, bcc?, from?, replyTo? })
insforge.payments.stripe	.createCheckoutSession(), .createCustomerPortalSession()
insforge.payments.razorpay	.createOrder(), .verifyOrder(), .createSubscription(), .verifySubscription(), .cancelSubscription(), .pauseSubscription(), .resumeSubscription()

重要注意事項

• 資料庫插入需要陣列格式：insert([{...}])
• Next.js / SSR 驗證：使用 @insforge/sdk/ssr 輔助函式（createBrowserClient、createServerClient、createAuthActions、createRefreshAuthRouter），並在 Proxy/Middleware 中從 @insforge/sdk/ssr/middleware 匯入 updateSession。將重新整理權杖設為 httpOnly，在伺服器上透過 createAuthActions() 執行驗證變更，從 Server Actions 僅回傳安全的應用程式資料，並讓瀏覽器讀取短效存取權杖以用於 Storage/Realtime。請參閱 auth/ssr-integration.md
• 儲存：將 url 和 key 都儲存至資料庫，以便進行下載/刪除操作
• 函式呼叫 URL：/functions/{slug}
• 電子郵件傳遞：驗證電子郵件（註冊驗證、密碼重設、魔法連結、邀請）在所有方案上皆可寄送。透過 insforge.emails.send() 的自訂電子郵件在所有付費方案上皆可寄送。使用平台管理的傳遞路徑；自訂寄件者網域為儀表板設定。請參閱 email/sdk-integration.md。
• 付款：首先使用 npx @insforge/cli payments <provider> ... 設定供應商金鑰/目錄；前端程式碼使用供應商範圍的 SDK 模組。
• 付款 RLS：在付款 UI 之前，在供應商執行時期資料表上新增應用程式特定的 RLS。Stripe 使用 payments.stripe_checkout_sessions 和 payments.stripe_customer_portal_sessions；Razorpay 使用 payments.razorpay_orders 和 payments.razorpay_subscriptions。持久的履行觸發器應放在 payments.webhook_events 上，而非成功 URL、Checkout 回呼或 payments.transactions。
• 使用 Tailwind CSS v3.4
• 部署前務必在本機建置：避免浪費建置資源並加快除錯速度
• SDK 套件：直接使用 @insforge/sdk 以獲得所有功能，包括驗證。
• 部署：在專案根目錄包含 vercel.json 以進行 SPA 路由（React、React Router 應用程式）。download-template 工具會自動包含此檔案。
• 針對有風險的後端變更使用分支：如果您的 SDK 程式碼依賴於新的 schema、RLS 政策或驗證設定變更，請先透過 npx @insforge/cli branch create 建立分支 — 請參閱 insforge-cli 技能的 branch 參考。在 branch create / branch switch 之後，更新應用程式的 InsForge URL 和匿名金鑰環境變數，然後重新啟動開發伺服器。