@shivaedev/admin 0.16.0 → 0.16.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.16.2 - 2026-11-01
4
+
5
+ ### Changed
6
+
7
+ - Update `@shivaedev/identity` from 0.14.0 to 0.15.0.
8
+ - Update `@shivaedev/jobs` from 0.28.2 to 0.28.3.
9
+ - Update `@shivaedev/react` from 0.30.1 to 0.31.0.
10
+
11
+ ## 0.16.1 - 2026-10-31
12
+
13
+ ### Changed
14
+
15
+ - Update `@shivaedev/identity` from 0.13.0 to 0.14.0.
16
+ - Update `@shivaedev/jobs` from 0.28.1 to 0.28.2.
17
+
3
18
  ## 0.16.0 - 2026-10-31
4
19
 
5
20
  ### Added
package/README.md CHANGED
@@ -28,6 +28,8 @@ An admin page is a native `@shivaedev/contract` contract plus a stable id, route
28
28
 
29
29
  Declare each page's queries, commands and streams with `@shivaedev/contract`, then pass its native contract to `adminPage`. The stable id identifies the page at server registration; route metadata belongs to the application's view. Author RPC namespaces in the contract name, such as `admin.jobs`.
30
30
 
31
+ For a wholly admin-only jobs feature, put this browser-safe declaration in `src/modules/admin/jobs/pages.ts`:
32
+
31
33
  ```ts
32
34
  import { Schema } from "effect";
33
35
  import { JobsPermission } from "@shivaedev/admin/permissions.ts";
@@ -40,18 +42,18 @@ const Failed = query("failed", {
40
42
  reads: () => [],
41
43
  success: Schema.Array(Schema.String),
42
44
  });
43
- const Jobs = adminPage({
45
+ export const Jobs = adminPage({
44
46
  id: "jobs",
45
47
  permission: JobsPermission,
46
48
  route: { path: "/admin/jobs", title: "Jobs" },
47
49
  contract: contract("admin.jobs", { queries: [Failed] }),
48
50
  });
49
- const Admin = adminRegistry(Jobs);
51
+ export const Admin = adminRegistry(Jobs);
50
52
  ```
51
53
 
52
54
  `Jobs.contract` keeps the native `.declaration` and `.application.toLayer` APIs. `adminRegistry(...pages)` returns `pages` and a native `group`. Duplicate page ids, route paths and RPC tags, including generated subscriptions, fail when the registry is created.
53
55
 
54
- Register server handler Layers by page id:
56
+ Register server handler Layers by page id in `src/modules/admin/jobs/server/registration.ts`, importing `Admin` and `Jobs` from that module's `pages.ts`:
55
57
 
56
58
  ```ts
57
59
  import { Effect, Layer } from "effect";
@@ -92,6 +94,53 @@ Provide `AdminSessions` once to `admin.handlers` and pass it with `admin.group`
92
94
 
93
95
  Browser composition uses `mergeAdminRegistries` from `@shivaedev/admin/registry.ts` with the modules' browser-safe registries. A client module can also contribute its registry's `pages` directly to the application's navigation. A feature module adds pages to its own registry and handlers to its own registration; the foundation does not import feature pages.
94
96
 
97
+ ### Keep admin code in admin paths
98
+
99
+ An `admin/` path segment means admin-only code. A wholly admin-only feature lives under `src/modules/admin/<name>`, with its shared declarations, `server/` and `client/` there. Admin tools for a member feature stay inside that feature: `admin/` for browser-safe page declarations, `server/admin/` for reads and handlers, and `client/admin/` for bindings and views. Each module reads only its own tables; compose another module's exposed operations for data it owns. Permissions enforce access regardless of the path.
100
+
101
+ The starter declares `StatisticsPage` with `adminPage` in [`src/modules/notes/admin/pages.ts`](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/modules/notes/admin/pages.ts). Its all-user read lives in [`src/modules/notes/server/admin/readStatistics.ts`](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/modules/notes/server/admin/readStatistics.ts):
102
+
103
+ ```ts
104
+ import { Effect, Schema } from "effect";
105
+ import { SqlClient, SqlSchema } from "effect/sql";
106
+ import { NoteStatistics } from "#modules/notes/admin/pages.ts";
107
+ import { notesSqlFailure } from "#modules/notes/server/sqlFailure.ts";
108
+
109
+ export const readStatistics = Effect.fn("Notes.readStatistics")(function* () {
110
+ const sql = yield* SqlClient.SqlClient;
111
+ const read = SqlSchema.findOne({
112
+ execute: () => sql`select count(*)::int as notes, count(*) filter (where word_count is null)::int as pending,
113
+ coalesce(sum(word_count), 0)::int as words from notes`,
114
+ Request: Schema.Void,
115
+ Result: NoteStatistics,
116
+ });
117
+ return yield* read(undefined).pipe(Effect.catchTag("SqlError", (cause) => Effect.fail(notesSqlFailure(cause))));
118
+ });
119
+ ```
120
+
121
+ [`src/modules/notes/server/admin/registration.ts`](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/modules/notes/server/admin/registration.ts) pairs that read with the page:
122
+
123
+ ```ts
124
+ import { registerAdmin } from "@shivaedev/admin/server/registerAdmin.ts";
125
+ import { rpcBoundary } from "@shivaedev/errors/boundary.ts";
126
+ import { InternalServerError } from "@shivaedev/errors/taxonomy.ts";
127
+ import { Admin, StatisticsPage } from "#modules/notes/admin/pages.ts";
128
+ import { readStatistics } from "./readStatistics.ts";
129
+
130
+ const statistics = StatisticsPage.contract.application.toLayer({
131
+ "admin.notes.statistics": () =>
132
+ readStatistics().pipe(
133
+ rpcBoundary(StatisticsPage.contract.declaration.queries[0].error, { unexpected: (message) => new InternalServerError({ message }) }),
134
+ ),
135
+ });
136
+
137
+ export const adminRegistration = registerAdmin(Admin, {
138
+ "note-statistics": statistics,
139
+ });
140
+ ```
141
+
142
+ The read stays in notes because notes owns the table. The [client registration](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/modules/notes/client/admin/registration.tsx) and view stay in `src/modules/notes/client/admin/`. Application composition may import these registrations from its member and admin module lists without moving their implementation out of the owning module.
143
+
95
144
  ### Built-in Jobs page
96
145
 
97
146
  Share each queue's name and payload Schema with the browser declaration. The page exposes only the queues passed to `jobsPage`; a queue registered with the jobs runtime is not automatically available to operators.
@@ -147,25 +147,7 @@ export declare function jobsPage<const TQueues extends readonly JobsEntry[]>(...
147
147
  readonly id: string;
148
148
  readonly queue: string;
149
149
  }, import("@shivaedev/errors/taxonomy.ts").BadRequest | import("#jobs/schemas.ts").JobsPayloadInvalid | import("#jobs/schemas.ts").JobsQueueUnregistered | import("#jobs/schemas.ts").JobsUnavailable, import("@shivaedev/identity/identity.ts").SessionUser>;
150
- }], readonly [], import("effect/rpc/Rpc").Rpc<"admin.jobs.job", Schema.Struct<{
151
- id: Schema.String;
152
- queue: Schema.String;
153
- }>, Schema.OptionFromNullOr<Schema.Union<Schema.Struct<{
154
- readonly attempt: Schema.Number;
155
- readonly completedOn: Schema.OptionFromNullOr<Schema.DateTimeUtcFromString>;
156
- readonly createdOn: Schema.DateTimeUtcFromString;
157
- readonly id: Schema.String;
158
- readonly output: Schema.NullOr<Schema.Struct<{
159
- readonly _tag: Schema.withDecodingDefaultKey<Schema.String, never>;
160
- readonly message: Schema.decodeTo<Schema.String, Schema.String, never, never>;
161
- }>>;
162
- readonly retryCount: Schema.Number;
163
- readonly retryLimit: Schema.Number;
164
- readonly startedOn: Schema.OptionFromNullOr<Schema.DateTimeUtcFromString>;
165
- readonly state: Schema.Literals<readonly ["created", "retry", "active", "completed", "cancelled", "failed"]>;
166
- readonly data: Schema.Unknown;
167
- readonly queue: Schema.Literal<string>;
168
- }>[]>>, Schema.Union<readonly [Schema.Union<readonly (typeof import("@shivaedev/errors/taxonomy.ts").BadRequest | typeof import("#jobs/schemas.ts").JobsUnavailable | typeof import("#jobs/schemas.ts").JobsPayloadInvalid | typeof import("#jobs/schemas.ts").JobsQueueUnregistered)[]>, typeof import("@shivaedev/contract/readPolicyErrors.ts").QueryReadDenied]>, typeof JobsPermission, never> | import("effect/rpc/Rpc").Rpc<"admin.jobs.$changes", Schema.Struct<{
150
+ }], readonly [], import("effect/rpc/Rpc").Rpc<"admin.jobs.$changes", Schema.Struct<{
169
151
  queries: Schema.$Array<Schema.Union<readonly (Schema.Struct<{
170
152
  query: Schema.Literal<"counts">;
171
153
  payload: Schema.Struct<{
@@ -220,20 +202,6 @@ export declare function jobsPage<const TQueues extends readonly JobsEntry[]>(...
220
202
  readonly failedCount: Schema.Number;
221
203
  readonly queuedCount: Schema.Number;
222
204
  readonly totalCount: Schema.Number;
223
- }>, Schema.Union<readonly [Schema.Union<readonly (typeof import("@shivaedev/errors/taxonomy.ts").BadRequest | typeof import("#jobs/schemas.ts").JobsUnavailable | typeof import("#jobs/schemas.ts").JobsPayloadInvalid | typeof import("#jobs/schemas.ts").JobsQueueUnregistered)[]>, typeof import("@shivaedev/contract/readPolicyErrors.ts").QueryReadDenied]>, typeof JobsPermission, never> | import("effect/rpc/Rpc").Rpc<"admin.jobs.health", Schema.Void, Schema.Struct<{
224
- readonly activeTotal: Schema.Number;
225
- readonly deadLetteredTotal: Schema.Number;
226
- readonly failedTotal: Schema.Number;
227
- readonly jobs: Schema.$Array<Schema.Struct<{
228
- readonly activeCount: Schema.Number;
229
- readonly deadLetteredCount: Schema.Number;
230
- readonly failedCount: Schema.Number;
231
- readonly name: Schema.String;
232
- readonly queuedCount: Schema.Number;
233
- readonly readyCount: Schema.Number;
234
- }>>;
235
- readonly queuedTotal: Schema.Number;
236
- readonly readyTotal: Schema.Number;
237
205
  }>, Schema.Union<readonly [Schema.Union<readonly (typeof import("@shivaedev/errors/taxonomy.ts").BadRequest | typeof import("#jobs/schemas.ts").JobsUnavailable | typeof import("#jobs/schemas.ts").JobsPayloadInvalid | typeof import("#jobs/schemas.ts").JobsQueueUnregistered)[]>, typeof import("@shivaedev/contract/readPolicyErrors.ts").QueryReadDenied]>, typeof JobsPermission, never> | import("effect/rpc/Rpc").Rpc<"admin.jobs.failed", Schema.Struct<{
238
206
  cursor: Schema.optionalKey<Schema.String>;
239
207
  limit: Schema.Number;
@@ -284,6 +252,38 @@ export declare function jobsPage<const TQueues extends readonly JobsEntry[]>(...
284
252
  readonly sourceQueue: Schema.Literal<string>;
285
253
  }>[]>>;
286
254
  readonly next: Schema.OptionFromNullOr<Schema.String>;
255
+ }>, Schema.Union<readonly [Schema.Union<readonly (typeof import("@shivaedev/errors/taxonomy.ts").BadRequest | typeof import("#jobs/schemas.ts").JobsUnavailable | typeof import("#jobs/schemas.ts").JobsPayloadInvalid | typeof import("#jobs/schemas.ts").JobsQueueUnregistered)[]>, typeof import("@shivaedev/contract/readPolicyErrors.ts").QueryReadDenied]>, typeof JobsPermission, never> | import("effect/rpc/Rpc").Rpc<"admin.jobs.job", Schema.Struct<{
256
+ id: Schema.String;
257
+ queue: Schema.String;
258
+ }>, Schema.OptionFromNullOr<Schema.Union<Schema.Struct<{
259
+ readonly attempt: Schema.Number;
260
+ readonly completedOn: Schema.OptionFromNullOr<Schema.DateTimeUtcFromString>;
261
+ readonly createdOn: Schema.DateTimeUtcFromString;
262
+ readonly id: Schema.String;
263
+ readonly output: Schema.NullOr<Schema.Struct<{
264
+ readonly _tag: Schema.withDecodingDefaultKey<Schema.String, never>;
265
+ readonly message: Schema.decodeTo<Schema.String, Schema.String, never, never>;
266
+ }>>;
267
+ readonly retryCount: Schema.Number;
268
+ readonly retryLimit: Schema.Number;
269
+ readonly startedOn: Schema.OptionFromNullOr<Schema.DateTimeUtcFromString>;
270
+ readonly state: Schema.Literals<readonly ["created", "retry", "active", "completed", "cancelled", "failed"]>;
271
+ readonly data: Schema.Unknown;
272
+ readonly queue: Schema.Literal<string>;
273
+ }>[]>>, Schema.Union<readonly [Schema.Union<readonly (typeof import("@shivaedev/errors/taxonomy.ts").BadRequest | typeof import("#jobs/schemas.ts").JobsUnavailable | typeof import("#jobs/schemas.ts").JobsPayloadInvalid | typeof import("#jobs/schemas.ts").JobsQueueUnregistered)[]>, typeof import("@shivaedev/contract/readPolicyErrors.ts").QueryReadDenied]>, typeof JobsPermission, never> | import("effect/rpc/Rpc").Rpc<"admin.jobs.health", Schema.Void, Schema.Struct<{
274
+ readonly activeTotal: Schema.Number;
275
+ readonly deadLetteredTotal: Schema.Number;
276
+ readonly failedTotal: Schema.Number;
277
+ readonly jobs: Schema.$Array<Schema.Struct<{
278
+ readonly activeCount: Schema.Number;
279
+ readonly deadLetteredCount: Schema.Number;
280
+ readonly failedCount: Schema.Number;
281
+ readonly name: Schema.String;
282
+ readonly queuedCount: Schema.Number;
283
+ readonly readyCount: Schema.Number;
284
+ }>>;
285
+ readonly queuedTotal: Schema.Number;
286
+ readonly readyTotal: Schema.Number;
287
287
  }>, Schema.Union<readonly [Schema.Union<readonly (typeof import("@shivaedev/errors/taxonomy.ts").BadRequest | typeof import("#jobs/schemas.ts").JobsUnavailable | typeof import("#jobs/schemas.ts").JobsPayloadInvalid | typeof import("#jobs/schemas.ts").JobsQueueUnregistered)[]>, typeof import("@shivaedev/contract/readPolicyErrors.ts").QueryReadDenied]>, typeof JobsPermission, never>, readonly [], undefined>;
288
288
  } & {
289
289
  queues: TQueues;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shivaedev/admin",
3
- "version": "0.16.0",
3
+ "version": "0.16.2",
4
4
  "description": "Explicit admin page contracts and a protected native Effect RPC registry",
5
5
  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/admin#readme",
6
6
  "bugs": {
@@ -46,16 +46,16 @@
46
46
  "@shivaedev/changes": "0.6.0",
47
47
  "@shivaedev/contract": "0.30.0",
48
48
  "@shivaedev/errors": "0.4.0",
49
- "@shivaedev/identity": "0.13.0",
50
- "@shivaedev/jobs": "0.28.1",
51
- "@shivaedev/react": "0.30.1"
49
+ "@shivaedev/identity": "0.15.0",
50
+ "@shivaedev/jobs": "0.28.3",
51
+ "@shivaedev/react": "0.31.0"
52
52
  },
53
53
  "devDependencies": {
54
54
  "@effect/atom-react": "4.0.6",
55
- "@shivaedev/quality": "0.52.0",
56
- "@shivaedev/server": "0.14.0",
57
- "@shivaedev/test-sql": "0.15.1",
58
- "@shivaedev/test-story": "0.31.1",
55
+ "@shivaedev/quality": "0.53.0",
56
+ "@shivaedev/server": "0.16.0",
57
+ "@shivaedev/test-sql": "0.15.3",
58
+ "@shivaedev/test-story": "0.31.3",
59
59
  "@types/node": "24.19.2",
60
60
  "@types/react": "19.3.0",
61
61
  "@types/react-dom": "19.3.0",