@synopackageland/sdk 0.0.0-stage → 0.9.1

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@synopackageland/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.1",
+  "description": "Frontend SDK for DSM packages built with synopkgland: headless client and Vue components",
+  "license": "MIT",
+  "homepage": "https://github.com/synopackageland/syno-pkg-land-sdk/tree/main/ts#readme",
+  "bugs": {
+    "url": "https://github.com/synopackageland/syno-pkg-land-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/synopackageland/syno-pkg-land-sdk.git",
+    "directory": "ts"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vue": {
+      "types": "./dist/src/vue.d.ts",
+      "import": "./dist/vue.js"
+    },
+    "./vue/style.css": "./dist/style.css",
+    "./i18n/*": "./dist/i18n/*"
+  },
+  "files": [
+    "dist",
+    "spec"
+  ],
+  "scripts": {
+    "prepack": "test -d node_modules || { echo '@synopackageland/sdk: run npm ci before npm pack' >&2; exit 1; }; npm run build",
+    "build": "vite build && vue-tsc -p tsconfig.build.json && cp -R i18n dist/ && rm -rf spec && cp -R ../spec spec",
+    "typecheck": "vue-tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@lucide/vue": "^1.48.0",
+    "@synopackageland/ui": "^0.9.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@lucide/vue": {
+      "optional": true
+    },
+    "@synopackageland/ui": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@lucide/vue": "1.48.0",
+    "@synopackageland/ui": "0.9.0",
+    "@types/node": "24.19.2",
+    "@vitejs/plugin-vue": "6.0.9",
+    "jsdom": "27.4.0",
+    "typescript": "5.9.3",
+    "vite": "7.3.6",
+    "vitest": "4.1.11",
+    "vue": "3.5.43",
+    "vue-tsc": "3.3.11"
+  }
+}

package/spec/protocol/v1/README.md

@@ -0,0 +1,112 @@
+# Executor protocol v1
+
+Since 0.9.0. The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD,
+SHOULD NOT, RECOMMENDED, MAY and OPTIONAL are to be interpreted as described in
+RFC 2119.
+
+The executor is a root process that a DSM package ships next to its app. The
+app asks it to act as a signed-in DSM user over a Unix socket. This directory
+is the protocol: the executor in `../../../executor` and the Go client in
+`../../../delegate` both conform to it, and `../../../conformance` checks
+the executor against the vectors here.
+
+| File | Contents |
+|---|---|
+| `schema/<op>.json` | JSON Schema (draft 2020-12) of the `params` of each op, with `since` |
+| `errors.json` | Every code: `code`, `kind`, `retryable`, `httpStatus`, `en`, `zh-TW`. The only source of codes; the Go constants are generated from it |
+| `vectors/*.jsonl` | One request per line: `{name, request, policy, state, expect}` |
+
+## Transport
+
+1. The socket is `/run/synopkgland/<package>/executor.sock`. The executor MUST
+   accept a connection only from the package user or root (peer credentials).
+2. A connection carries exactly one request and one response.
+3. A request is one line of UTF-8 JSON ending in `\n`. A request line MUST NOT
+   exceed 64 KiB including the newline; the executor answers
+   `REQUEST_TOO_LARGE`.
+4. The executor MUST answer one line of JSON ending in `\n` and close.
+5. The executor SHOULD close a connection that sends nothing for 15 seconds.
+
+## Request
+
+```json
+{"v":1,"op":"files.moveFromStaging","auth":{"dsm_cookie":"…","dsm_synotoken":"…"},"params":{…}}
+```
+
+- `v` MUST be `1`.
+- `op` MUST be one of the ops with a schema in `schema/`. An unknown op is
+  `UNKNOWN_OP`; an op outside the approved policy is `POLICY_DENIED`.
+- `auth` is OPTIONAL. When present it MUST contain only `dsm_cookie` and
+  `dsm_synotoken`. A present `auth` is always treated as caller
+  authentication, never ignored, even when empty. Ops whose schema says
+  `"auth": "required"` MUST be refused with `AUTH_DENIED` without a valid DSM
+  session.
+- `params` MUST be an object valid against `schema/<op>.json`. A member that
+  belongs to another op is `INVALID_REQUEST`.
+- The executor MUST refuse with `INVALID_REQUEST`: invalid UTF-8, duplicate
+  keys (compared with Unicode case folding), keys in `params` or `auth` other
+  than lowercase ASCII, digits and `_`, unknown members, and trailing data
+  after the object.
+
+## Response
+
+```json
+{"ok":true,"result":{…}}
+{"ok":false,"code":"SCOPE_DENIED","message":"scope denied"}
+```
+
+- `ok` is REQUIRED. On success `result` MUST be an object.
+- On refusal `code` MUST be a code of kind `refusal` in `errors.json`.
+  Clients MUST match on `code`, never on `message`.
+- A client MUST treat a reply that is not a JSON object with a boolean `ok`
+  as `EXECUTOR_PROTOCOL`, and an unreachable socket as
+  `EXECUTOR_UNAVAILABLE`. Codes of kind `client` are never sent by the
+  executor.
+
+## Status
+
+`status` answers `version` (`"1"`), `ready`, `disabled`, `executor_digest`
+and `policy_digest`. The executor MUST NOT report the SDK version; the binary
+digest MUST change only when the executor source changes.
+
+## Grants
+
+- A time-limited grant (`job_id`, `ttl_seconds` ≤ 30 days) covers the listed
+  `files.*` ops below `path`.
+- An until-revoked grant (`destination`, `lifetime: "until-revoked"`) covers
+  only `files.moveFromStaging` into one directory. A new grant for the same
+  user and destination MUST revoke the previous one (`destination-replaced`).
+- `files.taskStatus` and `files.taskCancel` follow the task's op and MUST NOT
+  be granted directly.
+- An administrator MAY turn the integration off with `delegate.disable`; then
+  `delegate.create` and every `files.*` op MUST be refused with `disabled`.
+
+## Asynchronous operations
+
+`files.moveFromStaging` admits an operation keyed by `job_id`. Sending the same
+`job_id` with the same input MUST return the existing operation; different
+input MUST be `operation-conflict`. States: `queued`, `copying`, `committed`,
+`canceled`, `interrupted`, `uncertain`. `files.operationStatus` and
+`files.cancelOperation` report the operation; `code` and `reason` in it are
+codes of kind `outcome` and `reason`.
+
+## Vectors
+
+Each line of `vectors/*.jsonl`:
+
+| Member | Meaning |
+|---|---|
+| `name` | Unique within its file |
+| `request` | The request object, or a JSON string sent as the raw line (for malformed input) |
+| `policy` | The approved policy the executor runs with |
+| `state` | Executor state before the request: `disabled`, and `grants` (`id`, `username`, `key`, `path`) as until-revoked home grants |
+| `expect` | The response. Objects match on the members listed; `"<any>"` matches any present value |
+
+The vector DSM knows `alice` (uid 1205), `bob` (1206) and `admin` (1207, an
+administrator). Their `dsm_cookie` is the user name and `dsm_synotoken` is
+`contract-token`.
+
+## Versioning
+
+New ops and members are added with a `since` of the SDK release. The protocol
+`v` changes only for an incompatible envelope change.

package/spec/protocol/v1/errors.json

@@ -0,0 +1,454 @@
+{
+  "$comment": "Single source of protocol v1 codes. kind: refusal = response code with ok false; outcome = operation record code; reason = operation record reason; client = produced by a client, never sent by the executor. httpStatus is the status an HTTP adapter SHOULD use.",
+  "since": "0.9.0",
+  "codes": [
+    {
+      "code": "AUTH_DENIED",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 401,
+      "en": "The DSM session in auth is missing, invalid or expired.",
+      "zh-TW": "auth 中的 DSM 工作階段缺少、無效或已過期。"
+    },
+    {
+      "code": "INELIGIBLE",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 403,
+      "en": "The DSM account cannot be delegated: system account, expired, or not the caller.",
+      "zh-TW": "此 DSM 帳號無法委派：系統帳號、已過期，或不是呼叫者本人。"
+    },
+    {
+      "code": "APP_DENIED",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 403,
+      "en": "DSM Application Privileges do not allow the account to use the app or File Station.",
+      "zh-TW": "DSM 應用程式權限不允許此帳號使用 App 或 File Station。"
+    },
+    {
+      "code": "ADMIN_REQUIRED",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 403,
+      "en": "The operation needs a DSM administrator.",
+      "zh-TW": "此操作需要 DSM 管理員。"
+    },
+    {
+      "code": "DELEGATION_DENIED",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 403,
+      "en": "The grant does not exist, belongs to another user or package, or was revoked.",
+      "zh-TW": "授權不存在、屬於其他使用者或套件，或已撤銷。"
+    },
+    {
+      "code": "SCOPE_DENIED",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 403,
+      "en": "The path is outside the grant or the approved folder scope.",
+      "zh-TW": "路徑超出授權或已核准的資料夾範圍。"
+    },
+    {
+      "code": "POLICY_DENIED",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 403,
+      "en": "The operation is not in the approved policy.",
+      "zh-TW": "此操作不在已核准的政策內。"
+    },
+    {
+      "code": "PEER_DENIED",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 403,
+      "en": "The socket peer is not the package user or root.",
+      "zh-TW": "socket 對端不是套件使用者或 root。"
+    },
+    {
+      "code": "PERMISSION_DENIED",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 403,
+      "en": "The delegated user cannot access the path in DSM.",
+      "zh-TW": "受委派的使用者在 DSM 中無法存取該路徑。"
+    },
+    {
+      "code": "UNKNOWN_OP",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 400,
+      "en": "The executor does not know the operation.",
+      "zh-TW": "executor 不認得此操作。"
+    },
+    {
+      "code": "INVALID_REQUEST",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 400,
+      "en": "The request or its params are not valid.",
+      "zh-TW": "請求或其 params 不合法。"
+    },
+    {
+      "code": "REQUEST_TOO_LARGE",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 413,
+      "en": "The request line is larger than 64 KiB.",
+      "zh-TW": "請求行超過 64 KiB。"
+    },
+    {
+      "code": "EXECUTOR_PAUSED",
+      "kind": "refusal",
+      "retryable": true,
+      "httpStatus": 503,
+      "en": "The executor is paused, for example while the package stops or upgrades.",
+      "zh-TW": "executor 已暫停，例如套件停止或升級期間。"
+    },
+    {
+      "code": "STORAGE_ERROR",
+      "kind": "refusal",
+      "retryable": true,
+      "httpStatus": 500,
+      "en": "The executor could not read or write its protected state.",
+      "zh-TW": "executor 無法讀寫其受保護的狀態。"
+    },
+    {
+      "code": "INTERNAL",
+      "kind": "refusal",
+      "retryable": true,
+      "httpStatus": 500,
+      "en": "The executor failed unexpectedly.",
+      "zh-TW": "executor 發生非預期的失敗。"
+    },
+    {
+      "code": "WRITE_FAILED",
+      "kind": "refusal",
+      "retryable": true,
+      "httpStatus": 500,
+      "en": "The executor could not write the file.",
+      "zh-TW": "executor 無法寫入檔案。"
+    },
+    {
+      "code": "READ_FAILED",
+      "kind": "refusal",
+      "retryable": true,
+      "httpStatus": 500,
+      "en": "The executor could not copy the file into staging.",
+      "zh-TW": "executor 無法把檔案複製到 staging。"
+    },
+    {
+      "code": "DSM_FAILED",
+      "kind": "refusal",
+      "retryable": true,
+      "httpStatus": 502,
+      "en": "A DSM call made by the executor failed.",
+      "zh-TW": "executor 呼叫 DSM 失敗。"
+    },
+    {
+      "code": "ROOT_FAILED",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 500,
+      "en": "The root operation exited with a non-zero status or failed to run.",
+      "zh-TW": "root 操作以非零狀態結束，或無法執行。"
+    },
+    {
+      "code": "NO_SPACE",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 507,
+      "en": "The destination volume is full.",
+      "zh-TW": "目的地的儲存空間已滿。"
+    },
+    {
+      "code": "SCOPE_APPROVAL_STALE",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "The folder scope approval is out of date.",
+      "zh-TW": "資料夾範圍的核准已過期。"
+    },
+    {
+      "code": "IDENTITY_CHANGED",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "The DSM account or folder the grant is bound to changed.",
+      "zh-TW": "授權所綁定的 DSM 帳號或資料夾已變更。"
+    },
+    {
+      "code": "needs-scope-confirmation",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "An administrator must confirm the folder scope first.",
+      "zh-TW": "管理員必須先確認資料夾範圍。"
+    },
+    {
+      "code": "disabled",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "An administrator turned the integration off.",
+      "zh-TW": "管理員已關閉這項整合。"
+    },
+    {
+      "code": "invalid-destination",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 400,
+      "en": "The destination key is not in the policy.",
+      "zh-TW": "目的地不在政策內。"
+    },
+    {
+      "code": "invalid-size",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 400,
+      "en": "The size is missing, negative or too large.",
+      "zh-TW": "檔案大小缺少、為負數或過大。"
+    },
+    {
+      "code": "operation-conflict",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "The same job id was sent again with different input.",
+      "zh-TW": "相同的 job id 又以不同的輸入送出。"
+    },
+    {
+      "code": "operation-not-found",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 404,
+      "en": "The operation is not known for this grant and caller.",
+      "zh-TW": "此授權與呼叫者沒有這項操作。"
+    },
+    {
+      "code": "destination-exists",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "A file with that name already exists and conflict does not allow replacing it.",
+      "zh-TW": "目的地已有同名檔案，且 conflict 不允許取代。"
+    },
+    {
+      "code": "invalid-path",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 400,
+      "en": "A name or path is empty, reserved, too long or contains a forbidden character.",
+      "zh-TW": "名稱或路徑為空、保留字、過長或含禁止字元。"
+    },
+    {
+      "code": "path-too-deep",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 400,
+      "en": "The name has more than 16 folders.",
+      "zh-TW": "名稱超過 16 層資料夾。"
+    },
+    {
+      "code": "destination-not-directory",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "A folder in the name exists as a file or symlink, or is on another volume.",
+      "zh-TW": "名稱中的某個資料夾其實是檔案或符號連結，或位於另一個磁碟區。"
+    },
+    {
+      "code": "name-too-long",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 400,
+      "en": "The volume refused a name as too long.",
+      "zh-TW": "磁碟區認為名稱過長而拒絕。"
+    },
+    {
+      "code": "not-found",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 404,
+      "en": "The path does not exist.",
+      "zh-TW": "路徑不存在。"
+    },
+    {
+      "code": "not-a-file",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 400,
+      "en": "The path is a folder or a special file.",
+      "zh-TW": "路徑是資料夾或特殊檔案。"
+    },
+    {
+      "code": "recursive-required",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 400,
+      "en": "The path is a folder and recursive is not set.",
+      "zh-TW": "路徑是資料夾，且未設定 recursive。"
+    },
+    {
+      "code": "recycle-bin-disabled",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "The Shared Folder has no recycle bin and permanent is not set.",
+      "zh-TW": "共用資料夾沒有資源回收筒，且未設定 permanent。"
+    },
+    {
+      "code": "task-not-found",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 404,
+      "en": "The task belongs to another job, or the executor restarted.",
+      "zh-TW": "任務屬於其他工作，或 executor 已重新啟動。"
+    },
+    {
+      "code": "too-many-tasks",
+      "kind": "refusal",
+      "retryable": true,
+      "httpStatus": 429,
+      "en": "The executor already tracks 64 tasks.",
+      "zh-TW": "executor 已在追蹤 64 個任務。"
+    },
+    {
+      "code": "queue-full",
+      "kind": "refusal",
+      "retryable": true,
+      "httpStatus": 429,
+      "en": "The executor operation queue is full.",
+      "zh-TW": "executor 的操作佇列已滿。"
+    },
+    {
+      "code": "limit-exceeded",
+      "kind": "refusal",
+      "retryable": false,
+      "httpStatus": 413,
+      "en": "The file is larger than max_bytes.",
+      "zh-TW": "檔案超過 max_bytes。"
+    },
+    {
+      "code": "OPERATION_CANCELED",
+      "kind": "outcome",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "The operation was canceled; reason says why.",
+      "zh-TW": "操作已取消；reason 說明原因。"
+    },
+    {
+      "code": "CANCEL_REQUESTED",
+      "kind": "outcome",
+      "retryable": false,
+      "httpStatus": 202,
+      "en": "Cancel was requested and the copy has not stopped yet.",
+      "zh-TW": "已要求取消，複製尚未停止。"
+    },
+    {
+      "code": "CLEANUP_PENDING",
+      "kind": "outcome",
+      "retryable": true,
+      "httpStatus": 500,
+      "en": "The operation ended but its partial file is not removed yet.",
+      "zh-TW": "操作已結束，但部分檔案尚未清除。"
+    },
+    {
+      "code": "grant-revoked",
+      "kind": "reason",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "The grant was revoked.",
+      "zh-TW": "授權已撤銷。"
+    },
+    {
+      "code": "destination-replaced",
+      "kind": "reason",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "A newer grant replaced this destination.",
+      "zh-TW": "較新的授權取代了此目的地。"
+    },
+    {
+      "code": "integration-disabled",
+      "kind": "reason",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "An administrator disabled the integration.",
+      "zh-TW": "管理員停用了此整合。"
+    },
+    {
+      "code": "validation-denied",
+      "kind": "reason",
+      "retryable": false,
+      "httpStatus": 403,
+      "en": "The grant failed revalidation against DSM.",
+      "zh-TW": "授權未通過 DSM 的重新驗證。"
+    },
+    {
+      "code": "scope-changed",
+      "kind": "reason",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "The approved folder scope changed.",
+      "zh-TW": "已核准的資料夾範圍已變更。"
+    },
+    {
+      "code": "storage-error",
+      "kind": "reason",
+      "retryable": true,
+      "httpStatus": 500,
+      "en": "Protected state could not be written.",
+      "zh-TW": "受保護的狀態無法寫入。"
+    },
+    {
+      "code": "operation-canceled-by-user",
+      "kind": "reason",
+      "retryable": false,
+      "httpStatus": 409,
+      "en": "The owner canceled the operation.",
+      "zh-TW": "擁有者取消了操作。"
+    },
+    {
+      "code": "operation-deadline-exceeded",
+      "kind": "reason",
+      "retryable": true,
+      "httpStatus": 504,
+      "en": "The operation ran past its deadline.",
+      "zh-TW": "操作超過期限。"
+    },
+    {
+      "code": "EXECUTOR_UNAVAILABLE",
+      "kind": "client",
+      "retryable": true,
+      "httpStatus": 503,
+      "en": "The client could not connect to the executor socket.",
+      "zh-TW": "用戶端無法連到 executor socket。"
+    },
+    {
+      "code": "EXECUTOR_TIMEOUT",
+      "kind": "client",
+      "retryable": true,
+      "httpStatus": 504,
+      "en": "The executor did not answer in time.",
+      "zh-TW": "executor 未及時回應。"
+    },
+    {
+      "code": "EXECUTOR_TOO_LARGE",
+      "kind": "client",
+      "retryable": false,
+      "httpStatus": 413,
+      "en": "The request or reply is larger than 64 KiB.",
+      "zh-TW": "請求或回應超過 64 KiB。"
+    },
+    {
+      "code": "EXECUTOR_PROTOCOL",
+      "kind": "client",
+      "retryable": false,
+      "httpStatus": 502,
+      "en": "The executor reply is not a valid v1 response.",
+      "zh-TW": "executor 的回應不是有效的 v1 回應。"
+    }
+  ]
+}

package/spec/protocol/v1/schema/delegate.audit.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/synopackageland/syno-pkg-land-sdk/spec/protocol/v1/schema/delegate.audit.json",
+  "title": "delegate.audit",
+  "description": "Administrator: read the audit log.",
+  "since": "0.9.0",
+  "auth": "required",
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}