@mortar-ai/skill 0.7.1 → 0.7.2

package/README.md

@@ -1,7 +1,8 @@
-# @mortar-ai/skill
+# Appunvs Cloud (Mortar) Skill
 
-[Agent Skills](https://agentskills.io/) package for building on **Mortar** (the
-BaaS that AI bundles talk to). Install the canonical `SKILL.md` and its
+[Agent Skills](https://agentskills.io/) package for building on **Appunvs
+Cloud**, powered by the Mortar BaaS. The package and Skill ID retain the stable
+`mortar` engineering name. Install the canonical `SKILL.md` and its
 `references/` into a compatible agent's skill directory to teach it the SDK
 core invariants plus on-demand capability references. The split keeps Fabric's
 loaded prompt small without hiding the storage, realtime, functions, auth, or

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mortar
-description: Build or change Fabric applications that use Mortar capabilities such as database, auth, storage, realtime, functions, analytics, automation, or messaging. Use for Mortar schema and provisioning, SDK integration, access policy, transactions, or backend consistency; not for Fabric's own control plane or a different backend.
+description: Build or change Fabric applications that use Appunvs Cloud capabilities powered by Mortar, such as database, auth, storage, realtime, functions, analytics, automation, or messaging. Use for Mortar schema and provisioning, SDK integration, access policy, transactions, or backend consistency; not for Fabric's own control plane or a different backend.
 metadata:
   activation: auto
   priority: high
@@ -8,10 +8,12 @@ metadata:
     - keywords: [database, 数据库, backend, 后端, auth, authentication, 登录, 认证, persistence, 持久化, transaction, 事务, ACID, storage, upload, 文件, realtime, 实时, collaboration, function, compute, analytics, cron, queue, comms, secrets, billing, cloud, 云端]
 ---
 
-# Mortar for Fabric applications
+# Appunvs Cloud (Mortar) for Fabric applications
 
-Mortar is an independent Backend-as-a-Service used by Fabric-built apps; Fabric
-itself does not run on Mortar. Do not infer its setup from another BaaS.
+Appunvs Cloud is the user-facing product powered by the independent Mortar
+Backend-as-a-Service. Fabric-built apps may use it; Fabric itself does not run
+on Mortar. `mortar` remains the stable SDK, tool, API, and source identity. Do
+not infer its setup from another BaaS.
 
 ## Fabric integration contract
 
@@ -81,7 +83,10 @@ below; if platform provisioning fails, report that platform failure.
    one-table batch or filtered mutation may use the public singleton;
    cross-table row + queue transactions require trusted server code; object
    storage and external services never join a PostgreSQL transaction.
-8. Type-check and build. Handle every `{ data, error }` SDK result in UI code.
+8. Read `references/errors.md` and handle both `{ data, error }` results and
+   thrown SDK failures according to the surrounding application's domain and
+   interaction design. Follow the application's existing architecture; Mortar
+   must not prescribe or introduce a shared UI adapter. Type-check and build.
 
 Supported database DDL is `CREATE TABLE`, `DROP TABLE`, `ALTER TABLE … ADD/DROP
 COLUMN`, `ALTER TABLE … SET ACCESS`, and `CREATE INDEX`. Put
@@ -106,7 +111,12 @@ type names guide application types but do not runtime-validate payload values.
   recreate a table merely to change permissions.
 - For a public form, registration, or evidence upload reviewed by an operator,
   use table/bucket access `public_insert`. It permits new submissions while
-  denying anonymous list, read, update, delete, and overwrite.
+  denying anonymous list, read, update, delete, and overwrite. That anonymous
+  restriction is not a blanket browser restriction: an authenticated AppUser
+  with `data_role=admin`, or trusted `app`/`admin` scope, may read and moderate
+  rows according to the server policy. Before deploying a Function for an
+  operator mutation, verify the active session and access policy; use the
+  authenticated SDK mutation directly when the data-admin path is supported.
 - Never use `public` merely to make anonymous submission work: it exposes all
   rows or files for public read and mutation.
 - Generate an unguessable logical object key for each public upload.
@@ -146,6 +156,8 @@ Agent Skills hosts resolve the same paths relative to this `SKILL.md`.
   `references/realtime.md`
 - Function deployment/invocation, logs, public-key boundaries, and error
   handling: `references/functions.md`
+- Normalized SDK errors, `{ data, error }` versus thrown calls, retry facts,
+  correlation IDs, and Function error ownership: `references/errors.md`
 - The 9 infrastructure primitives, open capability registry, application
   modules, usage accounting, and trust surfaces: `references/architecture.md`
 - Product analytics, error capture, delivery guarantees, and operator summary:
@@ -190,7 +202,8 @@ section.
   durable backend guarantee.
 - No secret/admin client or hand-written fallback configuration entered the
   client bundle.
-- Every SDK error path is handled.
+- Every SDK error path has an application-owned failure boundary; Mortar error
+  metadata does not dictate the application's UI or recovery flow.
 - The relevant on-demand reference—not every reference—was consulted.
 - Type-check and the surface's real build pass.
 

package/manifest.json

@@ -1,8 +1,8 @@
 {
   "schema_version": 1,
   "id": "mortar",
-  "version": "0.7.1",
-  "content_sha256": "sha256:515ca910b01c49b20a3838096bf4b1119be8c07879ab8eda220314d373dfeadd",
+  "version": "0.7.2",
+  "content_sha256": "sha256:b0240a03057ebc2cf8b831e198e5769644d5ea8a7645b7e5a7a6d22965db2ef1",
   "source_repo": "liamxujia/appunvs",
   "source_path": "mortar/skill",
   "distributions": [
@@ -11,6 +11,6 @@
   ],
   "npm": {
     "package": "@mortar-ai/skill",
-    "version": "0.7.1"
+    "version": "0.7.2"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mortar-ai/skill",
-  "version": "0.7.1",
-  "description": "Agent skill package for building Fabric applications on Mortar (BaaS), with compact core guidance and on-demand references.",
+  "version": "0.7.2",
+  "description": "Agent skill for building Fabric applications on Appunvs Cloud powered by Mortar, with compact core guidance and on-demand references.",
   "main": "index.js",
   "files": ["SKILL.md", "references", "manifest.json", "index.js", "README.md"],
   "bin": {

package/references/database.md

@@ -60,6 +60,38 @@ not claim direct public insert satisfies it. Use a reviewed supported
 server-side contract that really performs atomic deduplication, or state that
 the guarantee is not currently available for that client path.
 
+## `public_insert` and data-admin moderation
+
+`public_insert` means anonymous write-only intake, not that every browser
+session is forbidden from reading or changing rows. An authenticated AppUser
+whose current token has `data_role=admin` can read and moderate those rows;
+trusted `app` and `admin` scopes can do the same. The injected SDK resolves the
+managed AppUser session and attaches its access token automatically, so do not
+ask application code to copy tokens or put privileged project keys in a bundle.
+
+For an operator edit supported by that policy, use the authenticated singleton
+directly and handle the result:
+
+```ts
+const { data, error, count } = await mortar
+  .from('submissions')
+  .update({ display_name: cleanName })
+  .eq('id', submissionId)
+  .select();
+if (error) throw new Error(error.message);
+```
+
+If the target table has a database trigger that performs the required
+cross-table cascade, the triggering row update and that cascade run inside the
+database transaction. Moving the same update behind a Function does not make
+the database work more atomic; it only adds a compute/network boundary.
+
+Do not deploy a Function merely to bypass a policy that was not verified.
+Use trusted server code only when the current authenticated data-admin path is
+actually unsupported, or when the operation needs a server secret, an external
+provider, or a supported cross-table transaction that no database trigger
+already provides.
+
 ## Atomic row mutations
 
 Pass an array when every insert or upsert must succeed or fail together. Mortar

package/references/errors.md

@@ -0,0 +1,111 @@
+# Error handling reference
+
+Read this reference whenever application code calls Mortar. Mortar provides
+structured failure facts; the application owns their product meaning and user
+experience.
+
+## One normalized error, two JavaScript call shapes
+
+Mortar's TypeScript SDK exposes one canonical `MortarApiError` model:
+
+- `code`: stable machine code from the server's `error` field
+- `category`: technical class such as `validation`, `authentication`, `quota`,
+  `rate_limit`, `dependency`, `network`, or `timeout`
+- `status`: HTTP status, or `0` for a client/transport failure
+- `requestId`: correlation ID from `X-Request-ID`
+- `retryable` and `retryAfterMs`: transport and retry hints
+- `body`: the original structured server error
+
+Supabase-compatible query/auth/storage helpers return failures as
+`{ data, error }`. Other SDK methods throw `MortarApiError`. Both shapes carry
+the same underlying Mortar fields; the envelope changes control flow, not the
+meaning of the error.
+
+Always check an envelope's `error` before using `data`:
+
+```ts
+const { data, error } = await mortar.from('todos').insert(input);
+if (error) {
+  handleTodoCreateFailure(error); // Defined by this application and feature.
+  return;
+}
+useCreatedTodo(data);
+```
+
+Throwing APIs already expose `MortarApiError`. When a catch binding is
+`unknown`, `normalizeMortarError` converts transport and SDK failures into the
+same technical model without choosing application behavior:
+
+```ts
+import { normalizeMortarError } from '@mortar-ai/client';
+
+try {
+  await mortar.storage.upload({ bucket: 'receipts', key, body: file });
+} catch (cause) {
+  const error = normalizeMortarError(cause, 'upload receipt');
+  handleReceiptUploadFailure(error); // Application-defined, not SDK-defined.
+}
+```
+
+## Error facts are not interaction policy
+
+Mortar does not prescribe a toast, modal, inline field error, navigation,
+reauthentication flow, localization key, reporting rule, or centralized UI
+adapter. An application may handle failures per feature or reuse its own
+abstraction when that matches its architecture.
+
+In particular:
+
+- `category` is a technical grouping, not a UI action. For example,
+  `authentication` does not require immediate navigation to a sign-in screen.
+- `retryable` is a hint that the failure may succeed later, not permission to
+  replay the operation automatically.
+- `retryAfterMs` is server timing information, not a required countdown UI.
+- `requestId` supports correlation, but the application decides whether and
+  where it is recorded or presented.
+- `body`, `detail`, and `message` are diagnostic data. They are not guaranteed
+  to be localized, stable, sanitized for end users, or safe as control-flow
+  keys. Branch on stable codes and structured fields instead.
+
+Mutating operations are never automatically replayed without an idempotency guarantee.
+An insert, payment, message send, upload, or Function mutation may already have
+completed when the client observes a network failure. Require a documented
+idempotency contract or an explicit application decision before replaying it.
+
+## Function responses are a separate contract
+
+`mortar.compute.invoke(...)` throws only for Mortar platform failures marked by
+`X-Mortar-Error: platform`. A tenant Function's response stays a raw
+`Response`, including 4xx and 5xx statuses, because its business-error schema
+belongs to that Function:
+
+```ts
+try {
+  const response = await mortar.compute.invoke({
+    name: 'create-checkout',
+    body: JSON.stringify(input),
+    contentType: 'application/json',
+  });
+
+  if (!response.ok) {
+    const problem = await response.json();
+    applyCheckoutProblem(problem); // Function-owned application contract
+    return;
+  }
+} catch (error) {
+  handleCheckoutPlatformFailure(error); // Application-defined for this operation.
+}
+```
+
+Do not interpret a tenant Function's business body as a Mortar platform error,
+and do not infer error ownership from HTTP status alone.
+
+## Completion checks
+
+- Every `{ data, error }` result checks `error` before using `data`.
+- Every throwing Mortar operation has a deliberate application failure boundary.
+- Control flow uses stable error codes and fields rather than diagnostic text.
+- The application, not Mortar, determines UI, localization, navigation,
+  reporting, and recovery behavior.
+- Mutating operations are never automatically replayed without an idempotency guarantee.
+- Function business errors follow the Function's documented response schema.

package/references/functions.md

@@ -19,25 +19,51 @@ removes the manifest, both entrypoint forms, and the legacy flat `.js` artifact.
 Client bundles may invoke a function that the platform already deployed:
 
 ```ts
-const response = await mortar.compute.invoke({
-  name: 'create-checkout',
-  method: 'POST',
-  body: JSON.stringify({ orderId }),
-  contentType: 'application/json',
-});
-
-if (!response.ok) {
-  throw new Error(`Function failed: ${response.status} ${await response.text()}`);
+try {
+  const response = await mortar.compute.invoke({
+    name: 'create-checkout',
+    method: 'POST',
+    body: JSON.stringify({ orderId }),
+    contentType: 'application/json',
+  });
+
+  if (!response.ok) {
+    const problem = await response.json();
+    applyCheckoutProblem(problem); // Function-owned business contract
+    return;
+  }
+  const result = await response.json();
+  useCheckout(result);
+} catch (error) {
+  handleCheckoutPlatformFailure(error); // Application-defined for this operation.
 }
-const result = await response.json();
 ```
 
 `compute.invoke` is the only public-key compute operation. Mortar infrastructure
-errors such as unavailable compute or timeout throw; user-function status codes
-are returned as the raw `Response`, so check `response.ok` and consume the body.
+errors marked by `X-Mortar-Error: platform` throw; user-function status codes
+are returned as the raw `Response`, so check `response.ok` and consume the body
+according to that Function's documented business-error schema. HTTP status alone
+does not identify which side produced the error. See `errors.md` for the shared
+platform-error facts and the application-owned policy boundary.
 Function deployment/logs remain operator-side capabilities and must never be
 recreated with an app/admin key in a browser or mobile bundle.
 
+## When not to deploy a Function
+
+Check the authenticated row-policy path before introducing compute. In
+particular, `public_insert` denies anonymous reads and mutations but permits an
+authenticated AppUser with `data_role=admin` to moderate rows. When that path
+matches the product requirement, call the row SDK with the managed user session
+instead of deploying a Function merely to obtain an `app` scope.
+
+A database trigger invoked by one row mutation already runs in the database
+transaction with that mutation. Wrapping the update in a Function does not make
+the trigger cascade more atomic and adds a separate network/compute failure
+boundary. If a Function is genuinely required, authorize it with a verified
+user JWT or another server-trusted identity. Never accept caller-supplied names,
+employee numbers, roles, or similar request fields as proof of administrator
+identity.
+
 Functions and external providers do not join the caller's PostgreSQL
 transaction. Make externally visible operations idempotent and persist explicit
 pending/succeeded/failed state when a workflow must recover.

package/references/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Mortar REST API
-  version: "0.2.1"
+  version: "0.3.0"
   description: |
     Backend-as-a-Service for mainland-China-friendly mobile and web apps.
 
@@ -21,12 +21,12 @@ info:
       * `AccountToken` — Account session JWT minted by
         `/v1/_accounts/signin`, or an Account PAT (`mtr_pat_*`); scopes all
         `/v1/_accounts/*` and project-lifecycle calls to one Mortar account.
-      * `APIKey` — Bearer token starting with `mtr_live_` (production) or
-        `mtr_test_` (sandbox); scopes a single project (its tenant_id) and one of
-        `admin` / `app` / `public` privilege tiers.
+      * `APIKey` — raw `X-Mortar-API-Key` value starting with `mtr_live_`
+        (production) or `mtr_test_` (sandbox); scopes a single project (its
+        tenant_id) and one of `admin` / `app` / `public` privilege tiers.
 
     Signed-in project users may additionally send a User access JWT in
-    `X-Mortar-User-Token`.  That optional identity layer is not modeled
+    `Authorization: Bearer <jwt>`.  That optional identity layer is not modeled
     consistently by every operation in this partial document.
 
     Errors use a uniform `{ "error": "<machine_code>" }` body, occasionally
@@ -1856,12 +1856,19 @@ components:
         use and may be passed via the `MORTAR_ACCOUNT_TOKEN` env var to
         the `mortar` CLI.
     APIKey:
+      type: apiKey
+      in: header
+      name: X-Mortar-API-Key
+      description: |
+        Project-scope API key starting with `mtr_live_` (production) or
+        `mtr_test_` (sandbox), sent as the raw `X-Mortar-API-Key` value.
+    UserToken:
       type: http
       scheme: bearer
-      bearerFormat: opaque
+      bearerFormat: JWT
       description: |
-        Project-scope API key starting with `mtr_live_` (production) or
-        `mtr_test_` (sandbox).  Bearer-encoded in `Authorization`.
+        Optional project end-user access JWT in `Authorization: Bearer …`.
+        It supplements, and never replaces, the required `X-Mortar-API-Key`.
 
   parameters:
     TenantPath:
@@ -1895,21 +1902,57 @@ components:
   responses:
     BadRequest:
       description: Malformed request.
+      headers:
+        X-Request-ID:
+          $ref: "#/components/headers/RequestID"
+        X-Mortar-Error:
+          $ref: "#/components/headers/MortarErrorSource"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
 
+  headers:
+    RequestID:
+      description: Stable correlation ID echoed by Mortar for this request.
+      schema:
+        type: string
+    MortarErrorSource:
+      description: Present as `platform` when the response was generated by Mortar rather than a tenant Function.
+      schema:
+        type: string
+        enum: [platform]
+
   schemas:
     Error:
       type: object
-      required: [error]
+      required: [error, category, request_id]
       properties:
         error:
           type: string
           description: Machine-readable error code (e.g. `invalid_body`).
         detail:
           type: string
+          description: Optional diagnostic detail; applications should localize from `error` instead of displaying this directly.
+        category:
+          type: string
+          description: Stable application-level recovery category.
+          enum: [validation, authentication, permission, not_found, conflict, quota, rate_limit, dependency, internal]
+        request_id:
+          type: string
+          description: Correlation ID matching the `X-Request-ID` response header.
+        retryable:
+          type: boolean
+          description: Whether retrying may succeed. Mutating requests still require an idempotency-safe operation.
+        retry_after_sec:
+          type: integer
+          minimum: 0
+          description: Server-requested delay before retrying, also represented by `Retry-After` when present.
+        fields:
+          type: array
+          description: Optional application input fields associated with a validation error.
+          items:
+            type: string
 
     Account:
       type: object