base44-sdk

Base44 コーダー

Base44 JavaScript SDK を使用して、Base44 プラットフォーム上でアプリを構築します。

⚡ 直ちに対応が必要です — まずお読みください

「base44」という記述がある場合、または base44/ フォルダーが存在する場合、このスキルが有効になります。作業を開始する前に、ドキュメントファイルを読んだりウェブを検索したりしないでください。

最初に必ず行うこと：

1. 現在のディレクトリに base44/config.jsonc があるか確認します
2. ある場合（既存プロジェクトのシナリオ）：
   • このスキル（base44-sdk）がリクエストを処理します
   • Base44 SDK を使用して機能を実装します
   • ユーザーが CLI コマンドを明示的に要求しない限り、base44-cli は使用しないでください
3. ない場合（新規プロジェクトのシナリオ）：
   • プロジェクトの初期化のため、base44-cli スキルに引き継ぎます
   • プロジェクトが初期化されるまで、このスキルでは対応できません

このスキルと base44-cli の使い分け

base44-sdk を使用する場合：

• 既存の Base44 プロジェクトで機能を構築するとき
• プロジェクトに base44/config.jsonc がすでに存在するとき
• Base44 SDK のインポート（@base44/sdk）が存在するとき
• Base44 SDK モジュールを使用した JavaScript/TypeScript コードを書くとき
• 機能、コンポーネント、または機能性を実装するとき
• ユーザーが「実装する」「機能を構築する」「機能を追加する」「コードを書く」と言ったとき
• ユーザーが「[種類]のアプリを作成して」と言い、かつ Base44 プロジェクトがすでに存在するとき

base44-sdk を使用しない場合：

• ❌ 新しい Base44 プロジェクトを初期化するとき（代わりに base44-cli を使用）
• ❌ Base44 の設定がない空のディレクトリの場合
• ❌ ユーザーが「新しい Base44 プロジェクト／アプリ／サイトを作成して」と言い、プロジェクトが存在しない場合
• ❌ npx base44 create、npx base44 deploy、npx base44 login などの CLI コマンド（代わりに base44-cli を使用）

スキルの依存関係：

• base44-sdk は、Base44 プロジェクトがすでに初期化されていることを前提とします
• 新規プロジェクトでは、base44-sdk を使用するための前提条件として base44-cli が必要です
• ユーザーが「アプリを作成して」と希望し、Base44 プロジェクトが存在しない場合は、まず base44-cli を使用します

状態確認のロジック： このスキルを選択する前に、次の点を確認します。

• IF（ユーザーが「アプリを作成／構築」または「プロジェクトを作る」と言及している）：
  • IF（ディレクトリが空、または base44/config.jsonc が存在しない）： → base44-cli を使用します（プロジェクトの初期化が必要です）
  • ELSE： → base44-sdk を使用します（プロジェクトは存在するため、機能を構築します）

クイックスタート

// In Base44-generated apps, base44 client is pre-configured and available

// CRUD operations
const task = await base44.entities.Task.create({ title: "New task", status: "pending" });
const tasks = await base44.entities.Task.list();
await base44.entities.Task.update(task.id, { status: "done" });

// Get current user
const user = await base44.auth.me();

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

// IMPORTANT: Use 'appId' (NOT 'clientId' or 'id')
const base44 = createClient({ appId: "your-app-id" });
await base44.auth.loginViaEmailPassword("[email protected]", "password");

⚠️ 重要：API をでっち上げないでください

Base44 コードを書く前に、メソッド名をこの表または QUICK_REFERENCE.md で必ず確認してください。

Base44 SDK には独自のメソッド名があります。Firebase、Supabase、その他の SDK のパターンを当てはめないでください。

認証 — 誤りと正しい例

❌ 誤り（でっち上げ）	✅ 正しい例
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()

関数 — 誤りと正しい例

❌ 誤り（でっち上げ）	✅ 正しい例
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)

インテグレーション — 誤りと正しい例

❌ 誤り（誤った幻覚）	✅ 正しい例
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})

例外： base44.asServiceRole.aiGateway.connection() を指定した OpenAI 互換クライアント（Vercel AI SDK や openai SDK など）は正しい使い方です。これを使うことで、コードエージェント（ツールを使うエージェントのループ）を構築し、ゲートウェイの画像、動画、音声エンドポイントを呼び出せます。ツールを使わない単一の呼び出しには、InvokeLLM のみを使用してください。ai-gateway.md を参照してください。

アクター — 誤りと正しい例

❌ 誤り（誤った幻覚）	✅ 正しい例
actors.connect('ChatRoom', roomId)	actors.ChatRoom(roomId).connect()
actors.ChatRoom.connect(roomId)	actors.ChatRoom(roomId).connect()
actors.ChatRoom(roomId).subscribe(cb)	接続に対してサブスクライブします：const conn = actors.ChatRoom(roomId).connect(); conn.subscribe(cb)
room.on('message', cb)	room.subscribe(cb)（すべてのメッセージを受け取るコールバックは1つです）
room.emit(data)	room.send(data)
アプリのリアルタイム通信に new WebSocket(...) を使用	base44.actors.<Name>(id).connect()
const unsub = room.subscribe(cb); unsub()	const sub = room.subscribe(cb); sub.unsubscribe()

2つの subscribe() メソッドは異なる形式の値を返します。 Connection.subscribe()（アクター）はオブジェクトを返します — sub.unsubscribe()。entities.<Name>.subscribe() は、購読解除用の関数そのものを返します — unsub()。一方の慣例をもう一方に適用しないでください。

エンティティ — 誤りと正しい例

❌ 誤り（誤った幻覚）	✅ 正しい例
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
actors	WebSocket によるリアルタイムルーム（マルチプレイヤー、コラボレーション、プレゼンス）	actors.md
integrations	AI、メール、ファイルアップロード、カスタム API	integrations.md
aiGateway	Base44 の AI ゲートウェイ：コードエージェント、画像、動画、音声、構造化評価（Jev）	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 インターフェースと型をまとめた「Type Definitions」セクションがあります。

型付きのエンティティ、関数、アクター、エージェントを取得する： Base44 CLI はプロジェクトのリソース（エンティティ、関数、アクター、エージェント）から型を生成します。これには EntityTypeRegistry、FunctionNameRegistry、ActorNameRegistry、AgentNameRegistry の拡張が含まれます。また、手動設定なしで自動補完と型チェックを利用できるよう、生成した型をプロジェクトに組み込みます。型の生成方法については、base44-cli スキルをご覧ください。

手動での拡張： 代わりに、.d.ts ファイルでレジストリを自分で拡張することもできます。entities.md、functions.md、actors.md、base44-agents.md の「Type Definitions」セクションをご覧ください。アクターの message 型は必ず手動で定義します。アクターとそのクライアントで1つの定義を共有できるよう、ActorRegistry を拡張してください。

インストール

Base44 SDK をインストールします。

npm install @base44/sdk

重要： @base44/sdk パッケージのバージョンを推測したり、ハードコードしたりしないでください。常にバージョン指定なしでインストールし、最新バージョンを取得してください。

クライアントの作成（外部アプリ）

外部アプリでクライアントを作成する場合、パラメーター名には必ず appId を使用してください。

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

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

// ❌ WRONG - Do NOT use these:
// const base44 = createClient({ clientId: "your-app-id" });  // WRONG
// const base44 = createClient({ id: "your-app-id" });        // WRONG

必須パラメーター： appId（文字列）— Base44 アプリケーション ID

省略可能なパラメーター：

• token（文字列）— 認証済みユーザートークン
• options（オブジェクト）— 設定オプション
  • options.onError（関数）— グローバルエラーハンドラー

エラーハンドラーを使用する例：

const base44 = createClient({
  appId: "your-app-id",
  options: {
    onError: (error) => {
      console.error("Base44 error:", 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()
• デフォルト設定で画像を 1 枚生成 → integrations.Core.GenerateImage()
• 複数の画像、特定のモデル／アスペクト比／解像度、参照画像、または編集 → aiGateway の画像機能（ai-gateway.md を参照）
• シンプルなテキストから動画への変換 → integrations.Core.GenerateVideo()。モデルの選択、参照、またはフレームを使う場合 → 非同期ジョブである aiGateway の動画機能（ai-gateway.md を参照）
• テキスト読み上げ（TTS）または読み上げ機能 → ブラウザー／Core／ゲートウェイの選択については音声ガイドを参照してください。モデル固有のコントロールを実装したり、既存のゲートウェイ音声コードを編集したりする前にお読みください
• 基準に照らしてレコードを分類、採点、または振り分け → provider: "typesafe" を指定した aiGateway（Jev）。JSON スキーマを指定した InvokeLLM ではありません（ai-gateway.md を参照）
• ツールを備えたカスタムエージェントを構築（バックエンド、AI ゲートウェイ上のエージェント SDK） → aiGateway（ai-gateway.md を参照）

カスタムバックエンドロジックですか？

• サーバー側のコードを実行 → functions.invoke()
• 管理者アクセスが必要 → base44.asServiceRole.functions.invoke()

リアルタイムの共有セッションですか？

• マルチプレイヤー、共同編集ボード／ドキュメント、プレゼンス、ライブカーソル、ルーム内チャット → actors.<Name>(roomId).connect()（actors.md を参照）
• 画面上のレコード一覧をリアルタイムに保つだけの場合 → actors ではなく entities.EntityName.subscribe()

外部サービスですか？

• メールを送信 → 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 },  // query
  "-created_date",                             // sort (descending)
  10,                                          // limit
  0                                            // skip
);

保護されたルート（認証の確認）

const user = await base44.auth.me();
if (!user) {
  // Navigate to your custom login page
  navigate('/login', { state: { returnTo: window.location.pathname } });
  return;
}

バックエンド関数の呼び出し

// Frontend
// ⚠️ invoke() returns the RAW axios response — your function's JSON is on `.data`,
//    NOT the top-level object. It also THROWS on non-2xx (error body at err.response.data).
const res = await base44.functions.invoke("processOrder", {
  orderId: "123",
  action: "ship"
});
const result = res.data; // ✅ e.g. res.data.success  (res itself is { data, status, headers, … })

// Backend function
import { createClientFromRequest } from "npm:@base44/sdk";

export default async function (req) {
  const base44 = createClientFromRequest(req);
  const { orderId, action } = await req.json();
  // Process with service role for admin access
  const order = await base44.asServiceRole.entities.Orders.get(orderId);
  return Response.json({ success: true });
}

リアルタイムルーム（アクター）

// Frontend — connect inside useEffect and always clean up
useEffect(() => {
  const room = base44.actors.ChatRoom(roomId).connect();
  const sub = room.subscribe((msg) => {
    if (msg.type === "message") setMessages((prev) => [...prev, msg]);   // switch on type; drop unknowns
  });
  return () => { sub.unsubscribe(); room.close(); };   // NOTE: actors return { unsubscribe() },
}, [roomId]);                                          // entities.subscribe() returns the function itself

// Actor — base44/actors/ChatRoom/entry.ts
import { Actor } from "base44:runtime/actors";

export default class ChatRoom extends Actor {
  handleConnect(conn) { conn.send({ type: "welcome" }); }        // one client
  handleMessage(conn, msg) {
    // Always validate: the payload is attacker-controlled and msg can even be null.
    if (msg?.type !== "message" || typeof msg.text !== "string") return;
    this.broadcast({ type: "message", text: msg.text.slice(0, 2000) });   // everyone
  }
  handleClose(conn) {}
}

サービスロールによるアクセス

バックエンド関数で asServiceRole を使用すると、管理者レベルの操作を実行できます。アクターでは、正規の結果の永続化など、検証済みのルーム所有作業に this.client.asServiceRole を使用できます。ユーザーを明示的に識別する場合は、認証済み接続から取得した検証済みの conn.identity.userId を使用してください。actors.md を参照してください。

// User mode - respects permissions
const myTasks = await base44.entities.Task.list();

// Service role - full access (backend only)
const allTasks = await base44.asServiceRole.entities.Task.list();
const token = await base44.asServiceRole.connectors.getAccessToken("slack");

フロントエンドとバックエンド

機能	フロントエンド	バックエンド
entities（ユーザーのデータ）	はい	はい
auth	はい	はい
agents	はい	はい
functions.invoke()	はい	はい
functions.fetch()	はい	はい
actors（ルームへの接続）	はい	いいえ — アクター自体がサーバー側です
integrations	はい	はい
aiGateway	いいえ	はい
analytics	はい	はい
appLogs	はい	はい
users	はい	はい
asServiceRole.*	いいえ	はい
asServiceRole.connectors（アプリの OAuth）	いいえ	はい
asServiceRole.sso	いいえ	はい

バックエンド関数は、非同期リクエストハンドラーを export default し、createClientFromRequest(req) を使用して適切に認証されたクライアントを取得します。