base44-sdk

Base44 Coder

使用 Base44 JavaScript SDK 在 Base44 平台上建置應用程式。

⚡ 立即行動 - 請先閱讀此部分

此技能會在提及「base44」或存在 base44/ 資料夾時啟動。在採取行動之前，請勿讀取文件檔案或搜尋網路。

你的第一個動作必須是：

1. 檢查目前目錄中是否存在 base44/config.jsonc
2. 如果是（現有專案情境）：
   • 此技能（base44-sdk）處理請求
   • 使用 Base44 SDK 實作功能
   • 除非使用者明確要求 CLI 指令，否則不要使用 base44-cli
3. 如果否（新專案情境）：
   • 轉交給 base44-cli 技能進行專案初始化
   • 在專案初始化完成前，此技能無法提供協助

何時使用此技能 vs base44-cli

使用 base44-sdk 時機：

• 在現有的 Base44 專案中建置功能
• 專案中已存在 base44/config.jsonc
• 已匯入 Base44 SDK（@base44/sdk）
• 使用 Base44 SDK 模組撰寫 JavaScript/TypeScript 程式碼
• 實作功能、元件或特性
• 使用者提及：「實作」、「建置功能」、「加入功能」、「為...撰寫程式碼」
• 使用者說「建立一個 [類型] 應用程式」且 Base44 專案已存在

請勿使用 base44-sdk 於：

• ❌ 初始化新的 Base44 專案（請改用 base44-cli）
• ❌ 沒有 Base44 設定的空目錄
• ❌ 當使用者說「建立一個新的 Base44 專案/應用程式/網站」且沒有專案存在時
• ❌ CLI 指令如 npx base44 create、npx base44 deploy、npx base44 login（請使用 base44-cli）

技能相依性：

• base44-sdk 假設 Base44 專案已經初始化
• 對於新專案，base44-cli 是 base44-sdk 的先決條件
• 如果使用者想要「建立應用程式」且沒有 Base44 專案存在，請先使用 base44-cli

狀態檢查邏輯：
在選擇此技能前，請確認：

• 如果（使用者提及「建立/建置應用程式」或「製作一個專案」）：
  • 如果（目錄為空或沒有 base44/config.jsonc 存在）：
    → 使用 base44-cli（需要初始化專案）
  • 否則：
    → 使用 base44-sdk（專案已存在，建置功能）

快速開始

// 在 Base44 產生的應用程式中，base44 客戶端已預先設定好並可直接使用

// CRUD 操作
const task = await base44.entities.Task.create({ title: "新任務", status: "pending" });
const tasks = await base44.entities.Task.list();
await base44.entities.Task.update(task.id, { status: "done" });

// 取得目前使用者
const user = await base44.auth.me();

// 外部應用程式
import { createClient } from "@base44/sdk";

// 重要：使用 'appId'（不是 'clientId' 或 'id'）
const base44 = createClient({ appId: "your-app-id" });
await base44.auth.loginViaEmailPassword("user@example.com", "password");

⚠️ 重要：請勿憑空想像 API

在撰寫任何 Base44 程式碼之前，請對照此表格或 QUICK_REFERENCE.md 驗證方法名稱。

Base44 SDK 有獨特的方法名稱。請勿假設與 Firebase、Supabase 或其他 SDK 的模式相同。

認證 - 錯誤 vs 正確

❌ 錯誤（憑空想像）	✅ 正確
signInWithGoogle()	loginWithProvider('google')
signInWithProvider('google')	loginWithProvider('google')
auth.google()	loginWithProvider('google')
signInWithEmailAndPassword(email, pw)	loginViaEmailPassword(email, pw)
signIn(email, pw)	loginViaEmailPassword(email, pw)
createUser() / signUp()	register({email, password})
onAuthStateChanged()	me()（無監聽器，需要時呼叫）
currentUser	await auth.me()

函式 - 錯誤 vs 正確

❌ 錯誤（憑空想像）	✅ 正確
functions.call('name', data)	functions.invoke('name', data)
functions.run('name', data)	functions.invoke('name', data)
callFunction('name', data)	functions.invoke('name', data)
httpsCallable('name')(data)	functions.invoke('name', data)

整合 - 錯誤 vs 正確

❌ 錯誤（憑空想像）	✅ 正確
ai.generate(prompt)	integrations.Core.InvokeLLM({prompt})
openai.chat(prompt)	integrations.Core.InvokeLLM({prompt})
llm(prompt)	integrations.Core.InvokeLLM({prompt})
sendEmail(to, subject, body)	integrations.Core.SendEmail({to, subject, body})
email.send()	integrations.Core.SendEmail({to, subject, body})
uploadFile(file)	integrations.Core.UploadFile({file})
storage.upload(file)	integrations.Core.UploadFile({file})

例外： 一個相容 OpenAI 的客戶端（例如 Vercel AI SDK）是正確的，當它指向 base44.aiGateway.connection() 時——這就是你建置程式碼代理（帶工具的代理迴圈）的方式。僅在單次呼叫且無工具時使用 InvokeLLM。請參閱 ai-gateway.md。

實體 - 錯誤 vs 正確

❌ 錯誤（憑空想像）	✅ 正確
entities.Task.find({...})	entities.Task.filter({...})
entities.Task.findOne(id)	entities.Task.get(id)
entities.Task.insert(data)	entities.Task.create(data)
entities.Task.remove(id)	entities.Task.delete(id)
entities.Task.onChange(cb)	entities.Task.subscribe(cb)

SDK 模組

模組	用途	參考文件
entities	資料模型的 CRUD 操作	entities.md
auth	登入、註冊、使用者管理	auth.md
agents	AI 對話與訊息	base44-agents.md
functions	後端函式呼叫	functions.md
integrations	AI、電子郵件、檔案上傳、自訂 API	integrations.md
aiGateway	將相容 OpenAI 的 SDK 連接到 Base44 的 AI 閘道	ai-gateway.md
analytics	追蹤自訂事件與使用者活動	analytics.md
appLogs	記錄應用程式內的使用者活動	app-logs.md
users	邀請使用者加入應用程式	users.md
asServiceRole.connectors	應用程式範圍的 OAuth 令牌（僅服務角色）	connectors.md
asServiceRole.sso	SSO 令牌產生（僅服務角色）	sso.md

關於客戶端設定與認證模式，請參閱 client.md。

TypeScript 與型別註冊表

每個參考文件都包含一個「型別定義」章節，提供該模組方法、參數與回傳值的 TypeScript 介面與型別。

取得型別化的實體、函式與代理： Base44 CLI 會從你的專案資源（實體、函式、代理）產生型別，包括對 EntityTypeRegistry、FunctionNameRegistry 與 AgentNameRegistry 的擴充，並將其整合到你的專案中，讓你無需手動設定即可獲得自動完成與型別檢查。如需了解如何產生型別，請使用 base44-cli 技能。

手動擴充： 你也可以自己在 .d.ts 檔案中擴充註冊表；請參閱 entities.md、functions.md 與 base44-agents.md 中的型別定義章節。

安裝

安裝 Base44 SDK：

npm install @base44/sdk

重要： 切勿假設或硬編碼 @base44/sdk 套件版本。一律不安裝版本指定符，以取得最新版本。

建立客戶端（外部應用程式）

在外部應用程式中建立客戶端時，一律使用 appId 作為參數名稱：

import { createClient } from "@base44/sdk";

// ✅ 正確
const base44 = createClient({ appId: "your-app-id" });

// ❌ 錯誤 - 請勿使用以下方式：
// const base44 = createClient({ clientId: "your-app-id" });  // 錯誤
// const base44 = createClient({ id: "your-app-id" });        // 錯誤

必要參數： appId（字串）- 你的 Base44 應用程式 ID

選用參數：

• token（字串）- 預先認證的使用者令牌
• options（物件）- 設定選項
  • options.onError（函式）- 全域錯誤處理器

含錯誤處理器的範例：

const base44 = createClient({
  appId: "your-app-id",
  options: {
    onError: (error) => {
      console.error("Base44 錯誤：", error);
    }
  }
});

模組選擇

處理應用程式資料？

• 建立/讀取/更新/刪除記錄 → entities
• 從檔案匯入資料 → entities.importEntities()
• 即時更新 → entities.EntityName.subscribe()

使用者管理？

• 登入/註冊/登出 → auth
• 取得目前使用者 → auth.me()
• 更新使用者個人資料 → auth.updateMe()
• 邀請使用者 → users.inviteUser()

AI 功能？

• 與 AI 代理聊天 → agents（需要已登入的使用者）
• 建立新對話 → agents.createConversation()
• 管理對話 → agents.getConversations()
• 使用 AI 產生文字/JSON → integrations.Core.InvokeLLM()
• 產生圖片 → integrations.Core.GenerateImage()
• 使用工具建置自訂代理（後端，AI 閘道上的代理 SDK） → aiGateway（請參閱 ai-gateway.md）

自訂後端邏輯？

• 執行伺服器端程式碼 → functions.invoke()
• 需要管理員權限 → base44.asServiceRole.functions.invoke()

外部服務？

• 傳送電子郵件 → integrations.Core.SendEmail()
• 上傳檔案 → integrations.Core.UploadFile()
• 自訂 API → integrations.custom.call()
• 應用程式範圍的 OAuth（應用程式建置者的帳戶） → asServiceRole.connectors.getConnection()（僅後端）

追蹤與分析？

• 追蹤自訂事件 → analytics.track()
• 記錄頁面瀏覽/活動 → appLogs.logUserInApp()

常見模式

篩選與排序資料

const pendingTasks = await base44.entities.Task.filter(
  { status: "pending", assignedTo: userId },  // 查詢
  "-created_date",                             // 排序（降冪）
  10,                                          // 限制
  0                                            // 跳過
);

受保護的路由（檢查認證）

const user = await base44.auth.me();
if (!user) {
  // 導向你的自訂登入頁面
  navigate('/login', { state: { returnTo: window.location.pathname } });
  return;
}

後端函式呼叫

// 前端
// ⚠️ invoke() 回傳原始的 axios 回應 — 你的函式 JSON 在 `.data` 上，
//    而非頂層物件。它也會在非 2xx 狀態碼時拋出錯誤（錯誤內容在 err.response.data）。
const res = await base44.functions.invoke("processOrder", {
  orderId: "123",
  action: "ship"
});
const result = res.data; // ✅ 例如 res.data.success（res 本身是 { data, status, headers, … }）

// 後端函式（Deno）
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const { orderId, action } = await req.json();
  // 使用服務角色進行管理員權限操作
  const order = await base44.asServiceRole.entities.Orders.get(orderId);
  return Response.json({ success: true });
});

服務角色存取

在後端函式中使用 asServiceRole 進行管理層級操作：

// 使用者模式 - 遵守權限
const myTasks = await base44.entities.Task.list();

// 服務角色 - 完整存取（僅後端）
const allTasks = await base44.asServiceRole.entities.Task.list();
const token = await base44.asServiceRole.connectors.getAccessToken("slack");

前端 vs 後端

功能	前端	後端
entities（使用者的資料）	是	是
auth	是	是
agents	是	是
functions.invoke()	是	是
functions.fetch()	是	是
integrations	是	是
aiGateway	否	是
analytics	是	是
appLogs	是	是
users	是	是
asServiceRole.*	否	是
asServiceRole.connectors（應用程式 OAuth）	否	是
asServiceRole.sso	否	是

後端函式使用 Deno.serve() 與 createClientFromRequest(req) 來取得正確認證的客戶端。