API 参考

JavaScript SDK

SDK 是单个零依赖文件。加载它，再用你后端的数据 URL 和公开的 anon key（匿名密钥）创建客户端（两者都在 lingcode.dev/backends → 你的后端 里获取）。在 /try 和 Mac 预览里，客户端已预先注入为 window.lingcode。

<script src="https://lingcode.dev/sdk/lingcode-v1.js"></script>
<script>
  const lingcode = LingCode.createClient(url, anonKey, options?);
</script>

createClient(url, anonKey, options?)

• url: string —— 后端数据 URL，https://lingcode.dev/api/cloud/be/<backend-id>。
• anonKey: string —— 公开的 anon key（可以安全地放进浏览器里）。
• options.detectSessionInUrl?: boolean —— 默认 true；设为 false 可在构造时跳过从 URL 读取 ?lc_session/?lc_magic。

返回一个 LingCodeClient：

成员	类型	说明
url	string	后端数据 URL。
anonKey	string	当前使用的 anon key。
backendId	string	从 URL 解析出的后端 id。
ready	Promise<LingCodeClient>	在 URL 中的任何认证跳转被消费后 resolve。加载时 await 一次。
from(table)	QueryBuilder	开始一次数据查询。
auth · storage · functions · vector · push · telemetry · config	命名空间	见下文。

• from() / data
• auth
• storage
• functions
• vector
• push
• telemetry
• config

数据 —— from(table) → QueryBuilder

链式调用过滤器和修饰符，最后接一个终结操作。update() 和 delete() 必须带过滤器。完整指南：数据库。

方法	签名	说明
eq · neq · gt · gte · lt · lte	(column, value) => this	比较过滤器；多个之间为 AND。
like · ilike	(column, value: string) => this	子串匹配；ilike 不区分大小写。
in	(column, values: any[]) => this	成员归属。
is	(column, null | "not_null") => this	IS NULL / IS NOT NULL。
match	(filters: Record<string,any>) => this	一次设置多个相等过滤器。
order	(column, { ascending? }) => this	排序。
limit	(n: number) => this	限制行数（每页 ≤ 200）。
range	(from: number, to: number) => this	按索引分页。
select	() => Promise<Result<T[]>>	读取。
insert	(row | row[]) => Promise<Result<T[]>>	创建。
update	(patch) => Promise<Result<T[]>>	必须带过滤器。
delete	() => Promise<Result<T[]>>	必须带过滤器。
subscribe	(onChange, onError?) => Unsubscribe	实时 INSERT/UPDATE/DELETE，按 RLS 过滤。参见 实时。

auth —— client.auth

完整指南：认证。Session = { user: { id, email } | null, token }。

方法	签名
signUp	({ email, password }) => Promise<Result<Session>>
signIn · signInWithPassword	({ email, password }) => Promise<Result<Session>>
signInWithOAuth	(provider: "google"|"github"|"apple"|string, { redirectTo? }) => void —— 顶层导航跳转；返回时自动存储 session。
getProviders	() => Promise<Record<string, { available, source? }>>
sendMagicLink	({ email, redirectTo? }) => Promise<Result<{ sent }>>
verifyMagicLink	(token) => Promise<Result<Session>>
sendOtp	({ email }) => Promise<Result<{ sent }>>
verifyOtp	({ email, code }) => Promise<Result<Session>>
getUser	() => User | null
getToken	() => string | null
lastError	() => string | null —— 上一次跳转返回的 OAuth 错误码。
signOut	() => Promise<{ error: null }>

storage —— client.storage.from(bucket)

bucket 为 "public" 或 "private"。完整指南：存储。

方法	签名
upload	(path, file: Blob|File|ArrayBuffer|string, { contentType? }) => Promise<Result<{ bucket, path, bytes, url }>>
download	(path) => Promise<Result<Blob>>
getPublicUrl	(path) => string
remove	(path) => Promise<Result<{ removed }>>

functions —— client.functions

完整指南：函数。

方法	签名
invoke	<T>(slug: string, body?: any) => Promise<Result<T>>

vector —— client.vector

完整指南：向量检索。

方法	签名
search	({ table, column, embedding: number[], limit?, metric?: "cosine"|"l2"|"ip" }) => Promise<Result<T[]>>
embed	(input: string | string[]) => Promise<Result<{ embedding, embeddings, model, dimensions }>>

push —— client.push

方法	签名
isSupported	() => boolean
subscribe	({ serviceWorker? }) => Promise<Result<any>> —— 注册 service worker + PushManager 订阅，然后将其存储。

telemetry —— client.telemetry

方法	签名
logEvent	(name, params?: Record<string, string|number|boolean>) => void
logScreen	(name) => void
trace	(name, ms: number) => void
recordError	(err: Error | { message?, stack? } | string) => void
setUserId	(id: string | null) => void
setUserProperties	(props) => void
flush	() => Promise<Result>

config —— client.config

远程配置 + 实验变体。

成员	签名
ready	Promise<ConfigApi> —— 在配置加载完成后 resolve。
get	<T>(key, def?: T) => T
all	() => Record<string, any>

REST API

SDK 调用的就是这些。你可以从任何非 JS 客户端直接使用它们。面向应用的数据平面，基础 URL 是 https://lingcode.dev/api/cloud/be/<backend-id>。

数据

方法	路径	封装
POST	/select	from().select()
POST	/insert	from().insert()
POST	/update	from().update()（必须带过滤器）
POST	/delete	from().delete()（必须带过滤器）

请求体携带表名、过滤器以及行/补丁数据。运行时数据平面是表级 CRUD —— 不支持 JOIN，不支持 upsert，每页 ≤ 200 行（参见数据库）。

认证

方法	路径	请求体 / 说明
POST	/auth/signup	{ email, password }
POST	/auth/signin	{ email, password }
POST	/auth/magiclink/request	{ email, redirect_url }
POST	/auth/magiclink/verify	{ token }
POST	/auth/otp/request	{ email }
POST	/auth/otp/verify	{ email, code }
POST	/auth/apple/native	{ identity_token } —— 原生 Apple 登录
POST	/auth/token/refresh	{ refresh_token }
POST	/auth/signout	{ refresh_token } 或 { all: true } · 用户令牌
POST	/auth/mfa/enroll	→ { secret, qr_code } · 用户令牌
POST	/auth/mfa/verify	{ code } → AAL2 级别的 session · 用户令牌
POST	/auth/mfa/challenge	用户令牌
GET	/auth/mfa/factors	用户令牌
DELETE	/auth/mfa/factors/:factorId	用户令牌
GET	/auth/providers	→ { google, github, apple: { available, source } }
GET	/auth/oauth/:provider/start?redirect_url=…	302 → provider 授权页

OAuth 在 GET/POST /api/cloud/auth/oauth/:provider/callback 完成，它会跳转回你的 redirect_url：成功时带 ?lc_session=<jwt>，失败时带 ?lc_error=<code>。

存储

方法	路径	请求体 / 说明
POST	/storage/upload	{ bucket?, path, content_type?, data_b64 } → { bucket, path, bytes, url }
GET	/storage/object?bucket=…&path=…	文件本身（公开对象会 302 跳转到 CDN）
POST	/storage/remove	{ bucket?, path }
POST	/storage/create-upload-url	{ bucket?, path, content_type? } → { uploadUrl, method:"PUT", headers, bucket, path }
POST	/storage/finalize	{ bucket?, path } → { bucket, path, bytes, url }

向量 & 检索

方法	路径	请求体
POST	/vector/embed	{ input } → { embedding, embeddings, model, dimensions }
POST	/vector/search	{ table, column, embedding, limit?, metric? }
POST	/search/text	{ table, column, query, is_tsvector?, limit? }
POST	/search/hybrid	{ table, text_column, vector_column, query, embedding, … }

函数

方法	路径	请求体
POST	/functions/:slug	{ input? } → { ok, data } · 内置 + 自定义

实时

方法	路径	说明
GET	/realtime?table=foo,bar	SSE（text/event-stream）；发出 event: change / data: { table, type, row }；约 25s 一次心跳。参见实时。

推送、数据分析 & 配置

方法	路径	说明
GET	/push/vapid-public	→ { key }（VAPID 公钥）
POST	/push/subscribe	{ subscription }
POST	/telemetry	{ events: [...] }
GET	/config?client_id=…	→ 远程配置值

接下来