@raybase/api 0.0.2 → 0.1.0

package/dist/system-tables.js

@@ -0,0 +1,65 @@
+import { id, longText, raybaseSystemTable, text } from "@raybase/core";
+export const apiKeysTableName = "_api_keys";
+export const apiServicePrincipalsTableName = "_api_service_principals";
+export const apiKeyEventsTableName = "_api_key_events";
+export const raybaseApiSystemTables = [
+    raybaseSystemTable(apiServicePrincipalsTableName, {
+        id: id(),
+        label: text({ required: true }),
+        description: longText(),
+        ownerUserId: text({ required: true }),
+        defaultScopesJson: longText({ required: true }),
+        disabledAt: text(),
+        createdBy: text(),
+        createdAt: text({ required: true }),
+        updatedAt: text({ required: true })
+    }, {
+        label: "API service principals",
+        indexes: [["ownerUserId", "updatedAt"], ["disabledAt"]]
+    }),
+    raybaseSystemTable(apiKeysTableName, {
+        id: id(),
+        name: text({ required: true }),
+        description: longText(),
+        servicePrincipalId: text({ required: true }),
+        ownerUserId: text({ required: true }),
+        principalLabel: text({ required: true }),
+        prefix: text({ required: true, unique: true }),
+        hash: text({ required: true }),
+        scopesJson: longText({ required: true }),
+        expiresAt: text(),
+        revokedAt: text(),
+        revokedBy: text(),
+        revokedReason: longText(),
+        createdBy: text(),
+        createdAt: text({ required: true }),
+        rotatedAt: text(),
+        lastUsedAt: text(),
+        lastUsedIpHash: text(),
+        lastUsedUserAgent: text()
+    }, {
+        label: "API keys",
+        indexes: [
+            { columns: ["prefix"], unique: true },
+            ["servicePrincipalId", "createdAt"],
+            ["ownerUserId", "createdAt"],
+            ["revokedAt"],
+            ["lastUsedAt"]
+        ]
+    }),
+    raybaseSystemTable(apiKeyEventsTableName, {
+        id: id(),
+        keyId: text({ required: true }),
+        servicePrincipalId: text(),
+        ownerUserId: text(),
+        event: text({ required: true }),
+        actorUserId: text(),
+        requestId: text(),
+        metadataJson: longText(),
+        createdAt: text({ required: true })
+    }, {
+        label: "API key events",
+        indexes: [["keyId", "createdAt"], ["servicePrincipalId", "createdAt"], ["event", "createdAt"]]
+    })
+];
+//# sourceMappingURL=system-tables.js.map

package/dist/system-tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-tables.js","sourceRoot":"","sources":["../src/system-tables.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,16 +1,44 @@
 {
   "name": "@raybase/api",
-  "version": "0.0.2",
-  "description": "Reserved for Raybase. Nothing is released under this name yet.",
-  "license": "UNLICENSED",
+  "version": "0.1.0",
+  "description": "Optional first-party Raybase API key and external JSON API module.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates",
+    "skills"
+  ],
+  "peerDependencies": {
+    "@raybase/core": "0.3.3"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.27",
+    "@types/react-dom": "^18.3.7",
+    "esbuild": "^0.25.12",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.8.3",
+    "@raybase/core": "0.3.3"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/raybasedev/raybase.git"
+    "url": "git+https://github.com/raybasedev/raybase.git",
+    "directory": "packages/api"
   },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
-}
+  "scripts": {
+    "build": "node scripts/build-admin.mjs && tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.admin.json"
+  }
+}

package/skills/raybase-api/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: raybase-api
+description: Expose selected Raybase actions through the optional @raybase/api module with API keys and scopes.
+---
+
+# Raybase API
+
+Use this skill before adding or changing an app's external HTTP API surface.
+
+## Rules
+
+- Declare business behavior as `defineAction()` first.
+- Read `.agents/skills/raybase-actions/SKILL.md` for action declaration,
+  policy, row authorization, idempotency, annotations, and adapter guidance.
+- Every action exposed through `apiOperation()` must declare `output`;
+  `raybase doctor` fails external API routes whose linked action has no output
+  schema.
+- Expose only intentional actions with `apiOperation(action, ...)`.
+- Do not add API route handlers with business logic.
+- Keep API scopes separate from action policies. A key scope answers whether the key may call an operation; the action policy still decides whether the linked user may perform the work.
+- Do not expose actions marked `requiresInternalControl`.
+- Use resource scopes such as `tasks:read`, `tasks:write`, and `tasks:delete`.
+- API keys execute as existing Raybase users. Do not bypass policies with raw SQL or service executors.
+- Treat `RAYBASE_API_KEY_SECRET` as a long-lived production secret. In v1, changing it invalidates existing API keys because stored key hashes are HMAC-based.
+
+## Example
+
+```ts
+import { apiModule, apiOperation, defineApiOperations } from "@raybase/api";
+import { actions } from "../actions";
+
+export const api = apiModule({
+  prefix: "/api/v1",
+  operations: defineApiOperations({
+    completeTask: apiOperation(actions.completeTask, {
+      method: "POST",
+      path: "/tasks/:id/complete",
+      scopes: ["tasks:write"],
+      parseRequest: ({ params, body }) => ({ id: params.id, ...(body as object) })
+    })
+  })
+});
+```
+
+Pass the exported module to `createRaybaseApp({ modules: [api] })`.

package/templates/react-router/app/api/operations.ts

@@ -0,0 +1,8 @@
+import { apiModule, defineApiOperations } from "@raybase/api";
+
+// Add external API operations by adapting declared Raybase actions with
+// apiOperation(action, { method, path, scopes, parseRequest }).
+export const api = apiModule({
+  prefix: "/api/v1",
+  operations: defineApiOperations({})
+});

package/templates/tanstack-start/src/api/operations.ts

@@ -0,0 +1,15 @@
+import { apiModule, apiOperation, defineApiOperations } from "@raybase/api";
+import { actions } from "../actions";
+
+export const api = apiModule({
+  prefix: "/api/v1",
+  operations: defineApiOperations({
+    markTodoDone: apiOperation(actions.markTodoDone, {
+      method: "POST",
+      path: "/todos/:id/done",
+      scopes: ["todos:write"],
+      summary: "Mark todo done",
+      parseRequest: ({ params }) => ({ id: params.id })
+    })
+  })
+});

package/README.md

@@ -1,3 +0,0 @@
-# @raybase/api
-
-This name is reserved for Raybase. Nothing is released under it yet, and this package holds no code.