From 93465082f4222205021a9db8fb8f4a1c0d538e8a Mon Sep 17 00:00:00 2001 From: David Dal Busco Date: Wed, 4 Feb 2026 11:19:59 +0100 Subject: [PATCH 1/4] feat(functions): controller kind --- .../functions/src/sdk/schemas/controllers.ts | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/packages/functions/src/sdk/schemas/controllers.ts b/packages/functions/src/sdk/schemas/controllers.ts index f8e3658c9..d56fe3b32 100644 --- a/packages/functions/src/sdk/schemas/controllers.ts +++ b/packages/functions/src/sdk/schemas/controllers.ts @@ -10,7 +10,7 @@ import { } from '../../schemas/satellite'; /** - * @see ControllerScopeSchema + * @see ControllerScope */ export const ControllerScopeSchema = z.enum(['write', 'admin', 'submit']); @@ -19,6 +19,16 @@ export const ControllerScopeSchema = z.enum(['write', 'admin', 'submit']); */ export type ControllerScope = z.infer; +/** + * @see ControllerKind + */ +export const ControllerKindSchema = z.enum(['automation', 'emulator']); + +/** + * Represents a specific kind of controller. Meant for informational purposes. + */ +export type ControllerKind = z.infer; + /** * @see MetadataSchema */ @@ -38,7 +48,8 @@ export const ControllerSchema = z created_at: TimestampSchema, updated_at: TimestampSchema, expires_at: TimestampSchema.optional(), - scope: ControllerScopeSchema + scope: ControllerScopeSchema, + kind: ControllerKindSchema.optional(), }) .strict(); @@ -71,6 +82,11 @@ export interface Controller { * The scope assigned to the controller. */ scope: ControllerScope; + + /** + * An optional kind identifier of the controller. + */ + kind?: ControllerKind; } /** From 8cf81ff6552b1db0ce9bf8a61fccb1103e01e44f Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 4 Feb 2026 10:21:02 +0000 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=A4=96=20Documentation=20auto-update?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- packages/functions/README.md | 99 ++++++++++++++++++++++-------------- 1 file changed, 62 insertions(+), 37 deletions(-) diff --git a/packages/functions/README.md b/packages/functions/README.md index ad6282b83..bca593d1c 100644 --- a/packages/functions/README.md +++ b/packages/functions/README.md @@ -270,9 +270,9 @@ The raw user ID as a `Uint8Array`. Gets the list of admin controllers from the Satellite. -| Function | Type | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `getAdminControllers` | `() => [Uint8Array, { metadata: [string, string][]; created_at: bigint; updated_at: bigint; scope: "write" or "admin" or "submit"; expires_at?: bigint or undefined; }][]` | +| Function | Type | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `getAdminControllers` | `() => [Uint8Array, { metadata: [string, string][]; created_at: bigint; updated_at: bigint; scope: "write" or "admin" or "submit"; expires_at?: bigint or undefined; kind?: "automation" or ... 1 more ... or undefined; }][]` | Returns: @@ -284,9 +284,9 @@ The list of admin controllers. Gets the list of controllers from the Satellite. -| Function | Type | -| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `getControllers` | `() => [Uint8Array, { metadata: [string, string][]; created_at: bigint; updated_at: bigint; scope: "write" or "admin" or "submit"; expires_at?: bigint or undefined; }][]` | +| Function | Type | +| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `getControllers` | `() => [Uint8Array, { metadata: [string, string][]; created_at: bigint; updated_at: bigint; scope: "write" or "admin" or "submit"; expires_at?: bigint or undefined; kind?: "automation" or ... 1 more ... or undefined; }][]` | Returns: @@ -811,6 +811,7 @@ The current timestamp. - [ListOrderSchema](#gear-listorderschema) - [ListParamsSchema](#gear-listparamsschema) - [ControllerScopeSchema](#gear-controllerscopeschema) +- [ControllerKindSchema](#gear-controllerkindschema) - [MetadataSchema](#gear-metadataschema) - [ControllerSchema](#gear-controllerschema) - [ControllerRecordSchema](#gear-controllerrecordschema) @@ -1641,10 +1642,22 @@ References: References: -- ControllerScopeSchema +- ControllerScope [:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L15) +#### :gear: ControllerKindSchema + +| Constant | Type | +| ---------------------- | -------------------------------------------------------------- | +| `ControllerKindSchema` | `ZodEnum<{ automation: "automation"; emulator: "emulator"; }>` | + +References: + +- ControllerKind + +[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L25) + #### :gear: MetadataSchema | Constant | Type | @@ -1655,43 +1668,43 @@ References: - MetadataSchema -[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L25) +[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L35) #### :gear: ControllerSchema -| Constant | Type | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ControllerSchema` | `ZodObject<{ metadata: ZodArray>; created_at: ZodBigInt; updated_at: ZodBigInt; expires_at: ZodOptional<...>; scope: ZodEnum<...>; }, $strict>` | +| Constant | Type | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ControllerSchema` | `ZodObject<{ metadata: ZodArray>; created_at: ZodBigInt; updated_at: ZodBigInt; expires_at: ZodOptional<...>; scope: ZodEnum<...>; kind: ZodOptional<...>; }, $strict>` | References: - ControllerSchema -[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L35) +[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L45) #### :gear: ControllerRecordSchema -| Constant | Type | -| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ControllerRecordSchema` | `ZodTuple<[ZodCustom, Uint8Array>, ZodObject<{ metadata: ZodArray>; created_at: ZodBigInt; updated_at: ZodBigInt; expires_at: ZodOptional<...>; scope: ZodEnum<...>; }, $strict>], null>` | +| Constant | Type | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ControllerRecordSchema` | `ZodTuple<[ZodCustom, Uint8Array>, ZodObject<{ metadata: ZodArray>; ... 4 more ...; kind: ZodOptional<...>; }, $strict>], null>` | References: - ControllerRecordSchema -[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L79) +[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L95) #### :gear: ControllersSchema -| Constant | Type | -| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ControllersSchema` | `ZodArray, Uint8Array>, ZodObject<{ metadata: ZodArray>; created_at: ZodBigInt; updated_at: ZodBigInt; expires_at: ZodOptional<...>; scope: ZodEnum<...>; }, $strict>], null>>` | +| Constant | Type | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `ControllersSchema` | `ZodArray, Uint8Array>, ZodObject<{ metadata: ZodArray>; ... 4 more ...; kind: ZodOptional<...>; }, $strict>], null>>` | References: - ControllersSchema -[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L89) +[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L105) #### :gear: ControllerCheckParamsSchema @@ -1703,7 +1716,7 @@ References: - ControllerCheckParamsSchema -[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L99) +[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L115) #### :gear: CollectionParamsSchema @@ -2311,26 +2324,27 @@ List results, parameterized by type of returned item. Represents a controller with access scope and associated metadata. -| Property | Type | Description | -| ------------ | -------------------------------- | -------------------------------------------------------------------------------------------------- | -| `metadata` | `[string, string][]` | A list of key-value metadata pairs associated with the controller. | -| `created_at` | `bigint` | The timestamp when the controller was created. | -| `updated_at` | `bigint` | The timestamp when the controller was last updated. | -| `expires_at` | `bigint or undefined` | Optional expiration timestamp for the controller. 👉 It's a placeholder for future implementation. | -| `scope` | `"write" or "admin" or "submit"` | The scope assigned to the controller. | +| Property | Type | Description | +| ------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `metadata` | `[string, string][]` | A list of key-value metadata pairs associated with the controller. | +| `created_at` | `bigint` | The timestamp when the controller was created. | +| `updated_at` | `bigint` | The timestamp when the controller was last updated. | +| `expires_at` | `bigint or undefined` | Optional expiration timestamp for the controller. 👉 It's a placeholder for future implementation. | +| `scope` | `"write" or "admin" or "submit"` | The scope assigned to the controller. | +| `kind` | `"automation" or "emulator" or undefined` | An optional kind identifier of the controller. | -[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L48) +[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L59) #### :gear: ControllerCheckParams Represents the parameters required to perform controller checks. -| Property | Type | Description | -| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -| `caller` | `any` | The identity of the caller to verify against the controller list. | -| `controllers` | `[Uint8Array, { metadata: [string, string][]; created_at: bigint; updated_at: bigint; scope: "write" or "admin" or "submit"; expires_at?: bigint or undefined; }][]` | The list of controllers to check against. | +| Property | Type | Description | +| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | +| `caller` | `any` | The identity of the caller to verify against the controller list. | +| `controllers` | `[Uint8Array, { metadata: [string, string][]; created_at: bigint; updated_at: bigint; scope: "write" or "admin" or "submit"; expires_at?: bigint or undefined; kind?: "automation" or ... 1 more ... or undefined; }][]` | The list of controllers to check against. | -[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L107) +[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L123) #### :gear: CollectionParams @@ -2446,6 +2460,7 @@ Type representing the parameters required to make a canister call. - [TimestampMatcher](#gear-timestampmatcher) - [ListOrderField](#gear-listorderfield) - [ControllerScope](#gear-controllerscope) +- [ControllerKind](#gear-controllerkind) - [Metadata](#gear-metadata) - [ControllerRecord](#gear-controllerrecord) - [Controllers](#gear-controllers) @@ -3175,6 +3190,16 @@ Represents the permission scope of a controller. [:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L20) +#### :gear: ControllerKind + +Represents a specific kind of controller. Meant for informational purposes. + +| Type | Type | +| ---------------- | -------------------------------------- | +| `ControllerKind` | `z.infer` | + +[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L30) + #### :gear: Metadata Represents a single metadata entry as a key-value tuple. @@ -3183,7 +3208,7 @@ Represents a single metadata entry as a key-value tuple. | ---------- | -------------------------------- | | `Metadata` | `z.infer` | -[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L30) +[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L40) #### :gear: ControllerRecord @@ -3193,7 +3218,7 @@ Represents a tuple containing the principal ID and associated controller data. | ------------------ | ---------------------------------------- | | `ControllerRecord` | `z.infer` | -[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L84) +[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L100) #### :gear: Controllers @@ -3203,7 +3228,7 @@ Represents a list of controllers. | ------------- | ----------------------------------- | | `Controllers` | `z.infer` | -[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L94) +[:link: Source](https://github.com/junobuild/juno-js/tree/main/packages/functions/src/sdk/schemas/controllers.ts#L110) #### :gear: ListStoreParams From 639e79d11d6d81a275dee6212ba74743effd9be9 Mon Sep 17 00:00:00 2001 From: David Dal Busco Date: Wed, 4 Feb 2026 12:36:48 +0100 Subject: [PATCH 3/4] test: controller kind --- .../src/tests/sdk/schemas/controllers.spec.ts | 31 ++++++++++++++----- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/packages/functions/src/tests/sdk/schemas/controllers.spec.ts b/packages/functions/src/tests/sdk/schemas/controllers.spec.ts index 8a9af0c1a..364f60911 100644 --- a/packages/functions/src/tests/sdk/schemas/controllers.spec.ts +++ b/packages/functions/src/tests/sdk/schemas/controllers.spec.ts @@ -9,7 +9,7 @@ import {mockRawUserId, mockUserIdText} from '../../mocks/controllers.mock'; describe('controllers', () => { describe('ControllerSchema', () => { - const validController = { + const validFullController = { metadata: [ ['role', 'admin'], ['env', 'prod'] @@ -17,19 +17,21 @@ describe('controllers', () => { created_at: BigInt(1711900000000), updated_at: BigInt(1711905000000), expires_at: BigInt(1719999999999), - scope: 'admin' + scope: 'admin', + kind: 'automation' }; it('parses a valid controller', () => { - const result = ControllerSchema.parse(validController); + const result = ControllerSchema.parse(validFullController); expect(result.scope).toBe('admin'); + expect(result.kind).toBe('automation'); expect(result.metadata.length).toBe(2); }); it('fails if metadata is not an array of tuples', () => { expect(() => ControllerSchema.parse({ - ...validController, + ...validFullController, metadata: {role: 'admin'} }) ).toThrow(); @@ -38,26 +40,41 @@ describe('controllers', () => { it('fails if created_at is not a bigint', () => { expect(() => ControllerSchema.parse({ - ...validController, + ...validFullController, created_at: 1234567890 }) ).toThrow(); }); it('accepts missing expires_at (optional)', () => { - const {expires_at: _, ...withoutExpires} = validController; + const {expires_at: _, ...withoutExpires} = validFullController; const result = ControllerSchema.parse(withoutExpires); expect(result.expires_at).toBeUndefined(); }); + it('accepts missing kind (optional)', () => { + const {kind: _, ...withoutKind} = validFullController; + const result = ControllerSchema.parse(withoutKind); + expect(result.kind).toBeUndefined(); + }); + it('fails if scope is not in enum', () => { expect(() => ControllerSchema.parse({ - ...validController, + ...validFullController, scope: 'superadmin' }) ).toThrow(); }); + + it('fails if kind is not in enum', () => { + expect(() => + ControllerSchema.parse({ + ...validFullController, + kind: 'test' + }) + ).toThrow(); + }); }); describe('ControllerRecordSchema', () => { From e210f8522772e41f678c8fa9aca7d58e37e6abbe Mon Sep 17 00:00:00 2001 From: David Dal Busco Date: Wed, 4 Feb 2026 12:37:04 +0100 Subject: [PATCH 4/4] test: controller kind --- packages/functions/src/sdk/schemas/controllers.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/functions/src/sdk/schemas/controllers.ts b/packages/functions/src/sdk/schemas/controllers.ts index d56fe3b32..1570ff08b 100644 --- a/packages/functions/src/sdk/schemas/controllers.ts +++ b/packages/functions/src/sdk/schemas/controllers.ts @@ -49,7 +49,7 @@ export const ControllerSchema = z updated_at: TimestampSchema, expires_at: TimestampSchema.optional(), scope: ControllerScopeSchema, - kind: ControllerKindSchema.optional(), + kind: ControllerKindSchema.optional() }) .strict();