Skip to content

feat(functions): controller kind #729

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
peterpeterparker merged 5 commits into from
Feb 5, 2026
Merged

feat(functions): controller kind #729

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9346508
feat(functions): controller kind
peterpeterparker Feb 4, 2026
8cf81ff
🤖 Documentation auto-update
github-actions[bot] Feb 4, 2026
639e79d
test: controller kind
peterpeterparker Feb 4, 2026
319379a
Merge remote-tracking branch 'origin/feat/controller-kind' into feat/…
peterpeterparker Feb 4, 2026
e210f85
test: controller kind
peterpeterparker Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 62 additions & 37 deletions packages/functions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,9 +270,9 @@ The raw user ID as a `Uint8Array`.

Gets the list of admin controllers from the Satellite.

| Function | Type |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getAdminControllers` | `() => [Uint8Array<ArrayBufferLike>, { metadata: [string, string][]; created_at: bigint; updated_at: bigint; scope: "write" or "admin" or "submit"; expires_at?: bigint or undefined; }][]` |
| Function | Type |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getAdminControllers` | `() => [Uint8Array<ArrayBufferLike>, { 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:

Expand All @@ -284,9 +284,9 @@ The list of admin controllers.

Gets the list of controllers from the Satellite.

| Function | Type |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getControllers` | `() => [Uint8Array<ArrayBufferLike>, { metadata: [string, string][]; created_at: bigint; updated_at: bigint; scope: "write" or "admin" or "submit"; expires_at?: bigint or undefined; }][]` |
| Function | Type |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getControllers` | `() => [Uint8Array<ArrayBufferLike>, { 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:

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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 |
Expand All @@ -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<ZodTuple<[ZodString, ZodString], null>>; created_at: ZodBigInt; updated_at: ZodBigInt; expires_at: ZodOptional<...>; scope: ZodEnum<...>; }, $strict>` |
| Constant | Type |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ControllerSchema` | `ZodObject<{ metadata: ZodArray<ZodTuple<[ZodString, ZodString], null>>; 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<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>, ZodObject<{ metadata: ZodArray<ZodTuple<[ZodString, ZodString], null>>; created_at: ZodBigInt; updated_at: ZodBigInt; expires_at: ZodOptional<...>; scope: ZodEnum<...>; }, $strict>], null>` |
| Constant | Type |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ControllerRecordSchema` | `ZodTuple<[ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>, ZodObject<{ metadata: ZodArray<ZodTuple<[ZodString, ZodString], null>>; ... 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<ZodTuple<[ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>, ZodObject<{ metadata: ZodArray<ZodTuple<[ZodString, ZodString], null>>; created_at: ZodBigInt; updated_at: ZodBigInt; expires_at: ZodOptional<...>; scope: ZodEnum<...>; }, $strict>], null>>` |
| Constant | Type |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ControllersSchema` | `ZodArray<ZodTuple<[ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>, ZodObject<{ metadata: ZodArray<ZodTuple<[ZodString, ZodString], null>>; ... 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

Expand All @@ -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

Expand Down Expand Up @@ -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<ArrayBufferLike>, { 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<ArrayBufferLike>, { 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

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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<typeof ControllerKindSchema>` |

[: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.
Expand All @@ -3183,7 +3208,7 @@ Represents a single metadata entry as a key-value tuple.
| ---------- | -------------------------------- |
| `Metadata` | `z.infer<typeof MetadataSchema>` |

[: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

Expand All @@ -3193,7 +3218,7 @@ Represents a tuple containing the principal ID and associated controller data.
| ------------------ | ---------------------------------------- |
| `ControllerRecord` | `z.infer<typeof ControllerRecordSchema>` |

[: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

Expand All @@ -3203,7 +3228,7 @@ Represents a list of controllers.
| ------------- | ----------------------------------- |
| `Controllers` | `z.infer<typeof ControllersSchema>` |

[: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

Expand Down
20 changes: 18 additions & 2 deletions packages/functions/src/sdk/schemas/controllers.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import {
} from '../../schemas/satellite';

/**
* @see ControllerScopeSchema
* @see ControllerScope
*/
export const ControllerScopeSchema = z.enum(['write', 'admin', 'submit']);

Expand All @@ -19,6 +19,16 @@ export const ControllerScopeSchema = z.enum(['write', 'admin', 'submit']);
*/
export type ControllerScope = z.infer<typeof ControllerScopeSchema>;

/**
* @see ControllerKind
*/
export const ControllerKindSchema = z.enum(['automation', 'emulator']);

/**
* Represents a specific kind of controller. Meant for informational purposes.
*/
export type ControllerKind = z.infer<typeof ControllerKindSchema>;

/**
* @see MetadataSchema
*/
Expand All @@ -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();

Expand Down Expand Up @@ -71,6 +82,11 @@ export interface Controller {
* The scope assigned to the controller.
*/
scope: ControllerScope;

/**
* An optional kind identifier of the controller.
*/
kind?: ControllerKind;
}

/**
Expand Down
Loading