Keelson SDK

Keelson SDK は、アプリのコードから Keelson のファイル保存・ユーザー情報・バックグラウンドタスクなどの機能を使うためのライブラリです。Python・Node.js（JavaScript / TypeScript）・Go 向けに提供しており、必要な機能だけを使えます。

アプリをデプロイするだけなら SDK の導入は不要です。たとえば「アップロードされた画像を残したい」「ログイン中のユーザーに合わせて画面を変えたい」ときに、アプリへ組み込みます。AI エージェントに実装を依頼する場合も、使っている言語と実現したいことを伝え、このページや各機能の解説を渡せます。

できること

機能	できること・用途	使い方
Files SDK	アプリ内部で使う非公開ファイルの保存・読み取り・更新・削除・一覧取得。設定 JSON や処理済みデータの記録など	ファイルとメディア：Files
Media SDK	画像・PDF・添付ファイルの保存と、アプリを閲覧できるメンバー向けの URL 配信。商品写真の表示や申請書の閲覧など	ファイルとメディア：Media
Identity SDK	ログイン中のユーザー情報、所属グループ、ワークスペースのメンバー情報などの取得。作成者の記録やグループに応じた処理の分岐など	ログイン中のユーザー情報を使う
Tasks SDK	`keelson.yaml` の `tasks` に宣言したコマンドを、別のインスタンスで実行するよう投入し、状態を確認する。PDF の生成や外部 API の重い呼び出しなど、リクエストの後に続ける処理	バックグラウンドタスク

検索や同時更新が必要な顧客・案件などのデータには、データベース（Managed SQLite）を使います。接続には各言語の libSQL クライアントを使い、Keelson SDK とは別に導入します。

インストール

アプリの言語に合わせて、依存パッケージを追加します。基本的な機能は3言語で共通ですが、関数名や引数、補助機能は言語によって異なります。

Python

すべての機能を keelson-sdk にまとめています。

pip install keelson-sdk

コードでは、使う機能を from keelson import files のように読み込みます。files のほか、media、identity、tasks を使えます。利用する依存管理ツールに合わせて、requirements.txt や pyproject.toml にも依存関係を記録してください。

Node.js（JavaScript / TypeScript）

機能ごとにパッケージが分かれています。必要なものだけをインストールします。

機能	インストール
Files	`npm install @keelsonhq/files`
Media	`npm install @keelsonhq/media`
Identity	`npm install @keelsonhq/identity`
Tasks	`npm install @keelsonhq/tasks`

コードでは import * as files from "@keelsonhq/files" のように読み込みます。

Go

1つのモジュールに各機能のパッケージをまとめています。

go get github.com/keelsonhq/go-sdk

コードでは github.com/keelsonhq/go-sdk/files のように、使うパッケージを import します。files のほか、media、identity、tasks があり、メンバーやグループの一覧取得には directory を使います。

Keelson 上で使う

SDK はアプリのサーバー側で使います。ブラウザで動く JavaScript に組み込むものではありません。静的サイト・SPA にはサーバーがないため SDK は使えません。利用したい場合は、SDK を呼ぶ API サーバーを足してハイブリッド構成にします。

接続先や認証情報は、利用する機能に応じて Keelson が環境変数で渡します。通常は SDK が読み取るため、コードにトークンや保存先を書き込む必要はありません。

Files / Media：keelson.yaml への追加設定は不要です。
Identity：ヘッダーから基本的なユーザー情報を読むだけなら追加設定は不要です。所属グループやメンバー情報の取得には、Directory API の有効化と再デプロイが必要です。
Tasks：投入するタスクを keelson.yaml の tasks に宣言してデプロイします。詳しくはバックグラウンドタスクを参照してください。

ローカルで開発する

Files / Media は、Keelson の接続設定がない手元の環境ではローカルのフォルダに保存します。Identity は KEELSON_LOCAL_MODE=1 でテスト用のユーザー情報を返せます。Tasks は、CLI の keelson dev task run を使って手元でコマンドを同期実行します（手元で動かす）。ローカルで保存したファイルやテスト用のユーザー情報が、デプロイ先へ自動で引き継がれるわけではありません。

Files には言語と OS による制約があります。保存先や制約はファイルとメディアのローカル開発、ユーザー情報のテスト方法はIdentity のローカル開発を参照してください。SDK が使う設定値は環境変数リファレンスにまとめています。