OSDK

SDK 不是手写的，是从本体生成的。模型接口与结果行随本体重新生成；服务端函数里的查询面全类型，deno check 在编译期抓出属性拼写错误。

生成与安装

注册 SDK 应用（选定对象/行动/函数白名单），每次本体变更后调 regenerate 重新生成。包经实例内置的私有 registry 分发；registry 以组织作用域 PAT 鉴权（无组织作用域的令牌会收到 422 ORG_SCOPE_REQUIRED）：

# 签发组织作用域 PAT（服务账号 + scopes.org；$TOKEN 为你的登录令牌）
$ SVC=$(curl -s -X POST https://<实例>/v1/service-accounts \
    -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
    -d '{"name":"osdk-registry"}' \
    | node -pe 'JSON.parse(require("fs").readFileSync(0,"utf8")).id')
$ PAT=$(curl -s -X POST https://<实例>/v1/tokens \
    -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
    -d "{\"userId\":\"$SVC\",\"name\":\"registry\",
         \"scopes\":{\"org\":\"<组织>\"},\"expiresInDays\":90}" \
    | node -pe 'JSON.parse(require("fs").readFileSync(0,"utf8")).token')

# 注册 SDK 应用（控制台「管理 → SDK 应用」可查看清单）
$ curl -X POST https://<实例>/v1/sdk/apps -H "authorization: Bearer $TOKEN" \
    -H 'content-type: application/json' \
    -d '{"orgSlug":"<组织>","name":"<应用名>",
         "objectTypes":["part"],"actions":["restock"],"functions":[]}'

# TypeScript（npm 兼容 registry；组织作用域 PAT 即令牌）
$ npm config set @tesso:registry https://<实例>/v1/registry/npm/
$ npm config set //<实例>/v1/registry/npm/:_authToken <PAT>
$ npm install @tesso/osdk-<应用名>

# Python（PEP 503 simple registry；Basic 凭据带 PAT）
$ pip install --index-url https://token:<PAT>@<实例>/v1/registry/pypi/simple/ \
    tesso-osdk-<应用名>

# React 应用脚手架（生成工程内含 vendored hooks 与已配好的客户端）
$ tesso create app <应用名> --org <组织> --token <scoped-token>

TypeScript 查询面

import { client } from "./tesso";

// 对象集：where 过滤 → fetch 取数（结果行是生成的模型接口，全类型）
const low = await client.objects.part
  .where({ qty: { lt: 25 } })
  .fetch({ pageSize: 100, sort: [{ prop: "qty", dir: "asc" }] });

const byRegion = await client.objects.supplier.aggregate({
  metrics: [{ agg: "count" }],
  groupBy: ["region"],
});

比较子封闭清单：eq / neq / gt / gte / lt / lte / in / contains / startsWith / isNull。应用侧 OSDK 的模型接口与结果行全类型（where 子句宽松）；服务端函数 SDK 连 where 子句与属性名一并全类型。权限内联在查询里——你看不见的对象不会出现在结果与计数中。

写入走行动

OSDK 不提供裸写接口。所有写入经行动（Action）管线：校验、权限、审计、可回滚，一个不少。

// React：useAction 返回 TanStack Query mutation；默认进人工审核队列的行动
// 会如实返回 staged 态。hooks 由脚手架 vendored 到 src/vendor/tesso-react.ts。
import { useAction } from "./vendor/tesso-react";

const restock = useAction(client, "restock");
await restock.mutateAsync({ target: "P-1003" });

React hooks

hook	用途
`useObjects`	对象集查询（分页、排序、where）
`useObject`	单对象读取
`useLinks`	沿链接取对端对象
`useAction`	行动提交（含审核态回传）
`useSubscription`	SSE 实时订阅（他人编辑即时可见）

函数运行时同一套类型

服务端函数跑在 Deno 沙箱（默认全拒绝，仅允许回调网关），函数内的 objects.*.where().fetch() 与前端 OSDK 是同一套生成类型。tesso fn dev 拉取 sdk.ts 后，deno check 在编译期抓出属性拼写错误。

$ tesso fn dev
拉取 /v1/functions/<org>/sdk.ts → 本地全类型提示

REST 与 OpenAPI

全部 HTTP 面有 OpenAPI 描述：GET /v1/openapi.json。查询函数可发布为带版本的 REST API（/v1/functions/:org/:name/invoke/:version），以 scoped PAT 鉴权。