apaas-oapi-client 0.1.37 → 0.1.39

package/skills/apaas-schema/references/field-schema-rules.md

@@ -0,0 +1,98 @@
+# Field Schema Rules
+
+Use this reference before `client.schema.create` or `client.schema.update` field changes.
+
+- Verified source in this repo: `src/FIELD_SCHEMA_RULES.md`
+- Machine-readable source: `src/field-schema-rules.ts`
+- Verification date in source: `2026-02-10`
+
+## Metadata To Create Type Mapping
+
+| Metadata Type | Create Type | Notes |
+| --- | --- | --- |
+| `text` | `text` | Single-line text, commonly `max_length=255`. |
+| `text_multiline` | `text` | Use `multiline=true`, commonly `max_length=100000`. |
+| `bigint` | `bigint` | Same type name. |
+| `number` | `float` | `number` create type fails. |
+| `date` | `date` | Same type name. |
+| `datetime` | `datetime` | Same type name. |
+| `option` | `enum` | `option` create type fails. |
+| `boolean` | `boolean` | Same type name. |
+| `lookup` | `lookup` | Single value, `multiple=false`. |
+| `lookup_multi` | `lookup` | Multi value, `multiple=true`. |
+| `referenceField` | `reference_field` | Depends on a single-value lookup field. |
+| `file` | `attachment` | `file` create type fails. |
+| `autoId` | `auto_number` | `autoId` create type fails. |
+| `richText` | `richText` | Same type name. |
+| `mobileNumber` | `phone` | `mobileNumber` create type fails. |
+| `avatarOrLogo` | `avatar` | `avatarOrLogo` create type fails. |
+| `email` | `email` | Same type name. |
+| `region` | `region` | Same type name. |
+| `decimal` | `decimal` | Same type name. |
+| `multilingual` | `multilingual` | Same type name. |
+
+## Dependency Rules
+
+- Create target objects before lookup fields that reference them.
+- Create `lookup` or `lookup_multi` before `reference_field`.
+- Use only a single-value `lookup` as `reference_field.current_lookup_field_api_name`.
+- Do not use `lookup_multi` as the guide field for `reference_field`.
+- Remove `reference_field` before removing its lookup field.
+
+## Batch Update Rules
+
+- `add`: use `operator: "add"` and send the full field definition.
+- `replace`: use `operator: "replace"` and send full `type.name` plus `type.settings`.
+- `remove`: use `operator: "remove"` and send only `api_name`.
+- Label-only replace without `type` fails with `k_ec_000015 field type is required`.
+
+## Option Colors
+
+Allowed option colors:
+
+- `blue`
+- `cyan`
+- `green`
+- `yellow`
+- `orange`
+- `red`
+- `magenta`
+- `purple`
+- `blueMagenta`
+- `grey`
+
+## Minimal Lookup Example
+
+```ts
+{
+  operator: "add",
+  api_name: "owner",
+  label: { zh_cn: "负责人", en_us: "Owner" },
+  type: {
+    name: "lookup",
+    settings: {
+      objectAPIName: "_user",
+      multiple: false
+    }
+  },
+  encrypt_type: "none"
+}
+```
+
+## Minimal Reference Field Example
+
+```ts
+{
+  operator: "add",
+  api_name: "owner_lark_id",
+  label: { zh_cn: "负责人飞书 ID", en_us: "Owner Lark ID" },
+  type: {
+    name: "reference_field",
+    settings: {
+      current_lookup_field_api_name: "owner",
+      target_reference_field_api_name: "_lark_user_id"
+    }
+  },
+  encrypt_type: "none"
+}
+```

package/skills/apaas-shared/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: apaas-shared
+description: "Use for aPaaS Node SDK shared setup and safety rules: client initialization, credentials, namespace, token cache, logger level, pagination defaults, retry expectations, write/delete confirmation, and error triage before using module-specific apaas skills."
+---
+
+# aPaaS Shared
+
+Use this skill before module-specific aPaaS SDK work.
+
+## Baseline
+
+- Use the Node SDK package `apaas-oapi-client`.
+- Initialize one `apaas.Client` per namespace.
+- Keep `clientId`, `clientSecret`, access tokens, and app secrets out of logs and final answers.
+- Prefer `client.setLoggerLevel(3)` for normal work, `4` for debugging, and `5` only when inspecting non-sensitive payloads.
+- Treat SDK responses with `code !== "0"` as failed even if the HTTP call succeeded.
+
+```ts
+import { apaas } from "apaas-oapi-client";
+
+const client = new apaas.Client({
+  clientId: process.env.APAAS_CLIENT_ID!,
+  clientSecret: process.env.APAAS_CLIENT_SECRET!,
+  namespace: process.env.APAAS_NAMESPACE!
+});
+
+await client.init();
+client.setLoggerLevel(3);
+```
+
+## Safety Rules
+
+- Read real metadata before writing records, fields, flows, or pages.
+- Confirm user intent before destructive calls: record delete, batch delete, schema delete, field remove, attachment delete.
+- For batch operations, inspect `failed`, `failedCount`, or per-item success fields before reporting completion.
+- For full-table answers, use iterator methods and verify pagination is exhausted; a single page is only a sample.
+- Do not write system fields, readonly fields, formula outputs, lookup outputs, or reference field outputs as ordinary record values.
+
+## Module Routing
+
+- Object metadata and record CRUD: use `apaas-object`.
+- Object and field schema changes: use `apaas-schema`.
+- Cloud functions and automation flows: use `apaas-function-flow`.
+- Builder page metadata and links: use `apaas-builder`.
+- Global options and variables: use `apaas-global`.
+- User/department ID exchange and attachments: use `apaas-exchange-attachment`.
+
+## Error Triage
+
+| Symptom | First action |
+| --- | --- |
+| Permission or scope error | Verify app permissions and namespace; do not retry blindly. |
+| Field value type mismatch | Re-read `client.object.metadata.fields({ object_name })`. |
+| Missing field/object | Re-read object list or metadata; use API names from returned data. |
+| Batch partially failed | Report failed items and retry only failed IDs/records when safe. |
+| Rate limit or transient 5xx | Use SDK iterator/batch helpers and retry only idempotent reads or confirmed-safe writes. |

package/skills/apaas-shared/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "aPaaS Shared"
+  short_description: "aPaaS SDK 认证、凭证、安全与通用调用规则指南"
+  default_prompt: "Use $apaas-shared to initialize aPaaS SDK access safely."

package/.env

@@ -1,5 +0,0 @@
-CLIENT_APP_ID=c_fc919c38b7ab41a5ab36
-CLIENT_APP_SECRET=cad5106b819a43f286fb46a51b6ea2c8
-
-LARK_APP_ID=cli_a77cb9cd64b81013
-LARK_APP_SECRET=AEq56P8ntETGxNucLHTgbdLR2kNkXRNd

package/.github/workflows/publish.yml

@@ -1,36 +0,0 @@
-name: Node.js CI & Publish
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  build-test-publish:
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [22.x]
-
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
-        with:
-          node-version: ${{ matrix.node-version }}
-          registry-url: 'https://registry.npmjs.org/'
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Build
-        run: npm run build
-
-      - name: Run Tests
-        run: npm test
-
-      - name: Publish to npm
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.vscode/settings.json

@@ -1,9 +0,0 @@
-{
-    // Code Runner 配置：使用 tsx 运行 TypeScript 文件
-    "code-runner.executorMap": {
-        "typescript": "npx tsx"
-    },
-    "code-runner.runInTerminal": true,
-    "code-runner.clearPreviousOutput": true,
-    "code-runner.saveFileBeforeRun": true
-}