@atlasauth/backend 0.24.0 → 0.26.0

package/dist/client/fga.d.ts

@@ -29,13 +29,31 @@ export interface FgaTuple {
     relation: string;
     /** The object of the tuple as `type:id`. */
     target: string;
+    condition?: FgaTupleCondition;
     created_at: number;
 }
+/** A model condition bound to a tuple, with the parameter values fixed on it. */
+export interface FgaTupleCondition {
+    name: string;
+    context?: Record<string, unknown>;
+}
 /** A tuple key. `object` is the target as `type:id`; `target` is accepted too. */
 export interface FgaTupleKey {
     user: string;
     relation: string;
     object: string;
+    /** The tuple grants only while this model condition holds. */
+    condition?: FgaTupleCondition;
+}
+/**
+ * Freshness of a read. `MINIMIZE_LATENCY` (and the default) may be served from a
+ * short-lived cache; `HIGHER_CONSISTENCY` reads the primary.
+ */
+export type FgaConsistency = 'UNSPECIFIED' | 'MINIMIZE_LATENCY' | 'HIGHER_CONSISTENCY';
+export interface FgaConsistencyOptions {
+    consistency?: FgaConsistency;
+    /** A token from a write: the read reflects at least that write. */
+    consistency_token?: string;
 }
 /** An OpenFGA authorization model to persist. Validated before storage. */
 export interface FgaAuthorizationModelInput {
@@ -48,20 +66,80 @@ export interface FgaAuthorizationModelInput {
 export type FgaTupleKeys = FgaTupleKey[] | {
     tuple_keys: FgaTupleKey[];
 };
-export interface FgaCheckBody {
+export interface FgaCheckBody extends FgaConsistencyOptions {
     user: string;
     relation: string;
     object: string;
     /** Defaults to the store's latest model. */
     authorization_model_id?: string;
     contextual_tuples?: FgaTupleKeys;
+    /** Values for tuple-condition parameters (a tuple's own context wins). */
+    context?: Record<string, unknown>;
 }
-export interface FgaListObjectsBody {
+export interface FgaListObjectsBody extends FgaConsistencyOptions {
     user: string;
     relation: string;
     type: string;
     authorization_model_id?: string;
     contextual_tuples?: FgaTupleKeys;
+    /** Page size; without it every object is returned. */
+    limit?: number;
+    /** The `next_cursor` of the previous page. */
+    starting_after?: string;
+    context?: Record<string, unknown>;
+}
+export interface FgaListUsersBody extends FgaConsistencyOptions {
+    /** `type:id`. */
+    object: string;
+    relation: string;
+    /** Exactly one filter; add `relation` to get usersets such as `group:eng#member`. */
+    user_filters: [{
+        type: string;
+        relation?: string;
+    }];
+    authorization_model_id?: string;
+    contextual_tuples?: FgaTupleKeys;
+    context?: Record<string, unknown>;
+    /** 1–1000; defaults to 1000. */
+    page_size?: number;
+    continuation_token?: string;
+}
+export interface FgaListUsersResult {
+    object: 'fga.list_users';
+    /** `type:id`, `type:id#relation`, or `type:*` for a public wildcard. */
+    users: string[];
+    /** Ids a wildcard in `users` does not cover. */
+    excluded_users: string[];
+    /** Pass back for the next page; null on the last. */
+    continuation_token: string | null;
+    authorization_model_id: string;
+    consistency_token: string;
+}
+export interface FgaReadChangesParams {
+    /** Only changes to tuples on objects of this type. */
+    type?: string;
+    /** 1–100; defaults to 50. */
+    page_size?: number;
+    continuation_token?: string;
+    /** RFC 3339: only changes at or after it. */
+    start_time?: string;
+}
+export interface FgaTupleChange {
+    object: 'fga.tuple_change';
+    operation: 'write' | 'delete';
+    user: string;
+    relation: string;
+    target: string;
+    condition?: FgaTupleCondition;
+    consistency_token: string;
+    created_at: number;
+}
+export interface FgaChangesPage {
+    object: 'list';
+    data: FgaTupleChange[];
+    has_more: boolean;
+    /** Save it and call again later to receive only newer changes. */
+    continuation_token: string;
 }
 /** One item in a batch check; `correlation_id` is echoed back to match results. */
 export interface FgaBatchCheckItem {
@@ -70,16 +148,33 @@ export interface FgaBatchCheckItem {
     object: string;
     correlation_id?: string;
     contextual_tuples?: FgaTupleKeys;
+    context?: Record<string, unknown>;
 }
 export interface FgaBatchCheckResult {
     object: 'fga.batch_check';
     authorization_model_id: string;
+    consistency_token: string;
     result: Array<{
         correlation_id: string;
         allowed: boolean;
     }>;
 }
+/** How the instance runs FGA reads and keeps its tuple change log. */
+export interface FgaSettings {
+    object: 'fga.settings';
+    /** Result-cache TTL in ms; null uses the platform default, 0 turns the cache off. */
+    cache_ttl_ms: number | null;
+    /** Applied to reads that name no `consistency`. */
+    default_consistency: FgaConsistency;
+    /** Days of tuple change log kept; null keeps all of it. */
+    changelog_retention_days: number | null;
+}
+export type UpdateFgaSettingsBody = Partial<Omit<FgaSettings, 'object'>>;
 export declare function fgaResource(request: RequestFn): {
+    settings: {
+        get(): Promise<FgaSettings>;
+        update(body: UpdateFgaSettingsBody): Promise<FgaSettings>;
+    };
     stores: {
         list(): Promise<ListPage<FgaStore>>;
         create(body: {
@@ -105,6 +200,7 @@ export declare function fgaResource(request: RequestFn): {
         object: "fga.write_result";
         writes: number;
         deletes: number;
+        consistency_token: string;
     }>;
     /** Query stored tuples by any of user / relation / object. */
     read(storeId: string, body: {
@@ -117,18 +213,35 @@ export declare function fgaResource(request: RequestFn): {
         object: "fga.check";
         allowed: boolean;
         authorization_model_id: string;
+        consistency_token: string;
     }>;
     /** Resolve MANY access questions in one round trip (list-authorization UIs). */
     batchCheck(storeId: string, body: {
         checks: FgaBatchCheckItem[];
         authorization_model_id?: string;
-    }): Promise<FgaBatchCheckResult>;
+    } & FgaConsistencyOptions): Promise<FgaBatchCheckResult>;
     /** List the objects of a type a user has a relation to. */
     listObjects(storeId: string, body: FgaListObjectsBody): Promise<{
         object: "fga.list_objects";
         objects: string[];
+        has_more: boolean;
+        next_cursor: string | null;
         authorization_model_id: string;
+        consistency_token: string;
     }>;
+    /**
+     * Who has a relation on an object: concrete users, usersets (give the filter
+     * a `relation`) and the `type:*` wildcard with `excluded_users`. One page.
+     */
+    listUsers(storeId: string, body: FgaListUsersBody): Promise<FgaListUsersResult>;
+    /** {@link listUsers} following `continuation_token` until every page is collected. */
+    listAllUsers(storeId: string, body: FgaListUsersBody): Promise<FgaListUsersResult>;
+    /**
+     * The store's tuple change log, in commit order. The returned
+     * `continuation_token` works even on the last page: persist it and call again
+     * to receive only what changed since.
+     */
+    readChanges(storeId: string, params?: FgaReadChangesParams): Promise<FgaChangesPage>;
     /** Expand the full userset tree for an object#relation. */
     expand(storeId: string, body: {
         object: string;
@@ -153,6 +266,7 @@ export declare function fgaResource(request: RequestFn): {
             object: "fga.write_result";
             writes: number;
             deletes: number;
+            consistency_token: string;
         }>;
         read: (body: {
             user?: string;
@@ -163,16 +277,23 @@ export declare function fgaResource(request: RequestFn): {
             object: "fga.check";
             allowed: boolean;
             authorization_model_id: string;
+            consistency_token: string;
         }>;
         batchCheck: (body: {
             checks: FgaBatchCheckItem[];
             authorization_model_id?: string;
-        }) => Promise<FgaBatchCheckResult>;
+        } & FgaConsistencyOptions) => Promise<FgaBatchCheckResult>;
         listObjects: (body: FgaListObjectsBody) => Promise<{
             object: "fga.list_objects";
             objects: string[];
+            has_more: boolean;
+            next_cursor: string | null;
             authorization_model_id: string;
+            consistency_token: string;
         }>;
+        listUsers: (body: FgaListUsersBody) => Promise<FgaListUsersResult>;
+        listAllUsers: (body: FgaListUsersBody) => Promise<FgaListUsersResult>;
+        readChanges: (params?: FgaReadChangesParams) => Promise<FgaChangesPage>;
         expand: (body: {
             object: string;
             relation: string;

package/dist/client/fga.js

@@ -4,6 +4,14 @@ exports.fgaResource = fgaResource;
 const request_1 = require("./request");
 function fgaResource(request) {
     const api = {
+        settings: {
+            get() {
+                return request({ method: 'GET', path: '/v1/fga/settings' });
+            },
+            update(body) {
+                return request({ method: 'PUT', path: '/v1/fga/settings', body });
+            },
+        },
         stores: {
             list() {
                 return request({ method: 'GET', path: '/v1/fga/stores' });
@@ -60,6 +68,35 @@ function fgaResource(request) {
         listObjects(storeId, body) {
             return request({ method: 'POST', path: `/v1/fga/stores/${(0, request_1.enc)(storeId)}/list-objects`, body });
         },
+        /**
+         * Who has a relation on an object: concrete users, usersets (give the filter
+         * a `relation`) and the `type:*` wildcard with `excluded_users`. One page.
+         */
+        listUsers(storeId, body) {
+            return request({ method: 'POST', path: `/v1/fga/stores/${(0, request_1.enc)(storeId)}/list-users`, body });
+        },
+        /** {@link listUsers} following `continuation_token` until every page is collected. */
+        async listAllUsers(storeId, body) {
+            let page = await api.listUsers(storeId, body);
+            const users = [...page.users];
+            while (page.continuation_token) {
+                page = await api.listUsers(storeId, { ...body, continuation_token: page.continuation_token });
+                users.push(...page.users);
+            }
+            return { ...page, users };
+        },
+        /**
+         * The store's tuple change log, in commit order. The returned
+         * `continuation_token` works even on the last page: persist it and call again
+         * to receive only what changed since.
+         */
+        readChanges(storeId, params = {}) {
+            return request({
+                method: 'GET',
+                path: `/v1/fga/stores/${(0, request_1.enc)(storeId)}/changes`,
+                query: { ...params },
+            });
+        },
         /** Expand the full userset tree for an object#relation. */
         expand(storeId, body) {
             return request({ method: 'POST', path: `/v1/fga/stores/${(0, request_1.enc)(storeId)}/expand`, body });
@@ -77,6 +114,9 @@ function fgaResource(request) {
                 check: (body) => api.check(storeId, body),
                 batchCheck: (body) => api.batchCheck(storeId, body),
                 listObjects: (body) => api.listObjects(storeId, body),
+                listUsers: (body) => api.listUsers(storeId, body),
+                listAllUsers: (body) => api.listAllUsers(storeId, body),
+                readChanges: (params) => api.readChanges(storeId, params),
                 expand: (body) => api.expand(storeId, body),
                 models: {
                     list: () => api.models.list(storeId),

package/dist/client/fga.js.map

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

package/dist/client/flags.d.ts

@@ -0,0 +1,101 @@
+import { type RequestFn } from './request';
+import type { CursorParams } from './types';
+export type FeatureFlagType = 'boolean' | 'string' | 'int' | 'json';
+export type FeatureFlagValue = boolean | string | number | Record<string, unknown> | unknown[];
+/** Who a flag is evaluated for. `user_id` (else `org_id`) seeds percentage rollouts. */
+export interface FeatureFlagSubject {
+    user_id?: string | null;
+    org_id?: string | null;
+    plan?: string | null;
+}
+/** Every given `match` dimension must hold; an empty rule matches everyone. */
+export interface FeatureFlagRule {
+    match?: {
+        user_ids?: string[];
+        org_ids?: string[];
+        plans?: string[];
+    };
+    /** 0–100: the share of matching subjects, stable per flag and subject. */
+    percentage?: number;
+    value: FeatureFlagValue;
+}
+export interface FeatureFlag {
+    object: 'feature_flag';
+    id: string;
+    key: string;
+    type: FeatureFlagType;
+    description: string | null;
+    enabled: boolean;
+    default_value: FeatureFlagValue;
+    /** Returned while the flag is switched off. */
+    off_value: FeatureFlagValue;
+    rules: FeatureFlagRule[];
+    created_at: number;
+    updated_at: number;
+}
+export interface CreateFeatureFlagBody {
+    key: string;
+    type: FeatureFlagType;
+    default_value: FeatureFlagValue;
+    description?: string;
+    enabled?: boolean;
+    off_value?: FeatureFlagValue;
+    rules?: FeatureFlagRule[];
+}
+export type UpdateFeatureFlagBody = Partial<Omit<CreateFeatureFlagBody, 'key' | 'type'>>;
+export interface FeatureFlagEvaluation {
+    object: 'feature_flag_evaluation';
+    subject: FeatureFlagSubject;
+    flags: Record<string, {
+        value: FeatureFlagValue;
+        reason: string;
+    }>;
+}
+export interface AssignEntitlementsBody {
+    plan?: string | null;
+    features?: string[] | null;
+    limits?: Record<string, unknown> | null;
+    /** Epoch ms; omit for open-ended. */
+    expires_at?: number | null;
+}
+export interface AssignedEntitlements {
+    object: 'assigned_entitlements';
+    subject_type: 'user' | 'org';
+    subject_id: string;
+    plan: string | null;
+    features: string[] | null;
+    limits: Record<string, unknown> | null;
+    expires_at: number | null;
+}
+/** Evaluate a flag definition for a subject (first matching in-bucket rule wins, else the default). */
+export declare function evaluateFeatureFlag(flag: FeatureFlag, subject: FeatureFlagSubject): FeatureFlagValue;
+export declare function flagsResource(request: RequestFn, cacheTtlMs?: number): {
+    create(body: CreateFeatureFlagBody, idempotencyKey?: string): Promise<FeatureFlag>;
+    /** `starting_after` is the key of the last flag of the previous page. */
+    list(params?: CursorParams): Promise<{
+        object: "list";
+        data: FeatureFlag[];
+        has_more: boolean;
+    }>;
+    retrieve(key: string): Promise<FeatureFlag>;
+    update(key: string, body: UpdateFeatureFlagBody): Promise<FeatureFlag>;
+    delete(key: string): Promise<{
+        object: "feature_flag";
+        id: string;
+        key: string;
+        deleted: boolean;
+    }>;
+    /** Server-side evaluation; `plan` defaults to the org's (else the user's) resolved plan. */
+    evaluate(body: FeatureFlagSubject & {
+        keys?: string[];
+    }): Promise<FeatureFlagEvaluation>;
+    /** Local evaluation against cached definitions. `plan` is not looked up here — pass it for plan rules. */
+    get<T extends FeatureFlagValue>(key: string, subject: FeatureFlagSubject, fallback: T): Promise<T>;
+    /** True only for a boolean flag that evaluates to true; an unknown flag is false. */
+    isEnabled(key: string, subject?: FeatureFlagSubject): Promise<boolean>;
+    /** Drop the cached definitions (e.g. after changing a flag). */
+    invalidate(): void;
+    /** Replace the entitlements assigned to an organization (an empty body clears them). */
+    assignOrganizationEntitlements(orgId: string, body: AssignEntitlementsBody): Promise<AssignedEntitlements>;
+    assignUserEntitlements(userId: string, body: AssignEntitlementsBody): Promise<AssignedEntitlements>;
+};

package/dist/client/flags.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateFeatureFlag = evaluateFeatureFlag;
+exports.flagsResource = flagsResource;
+const sha256_1 = require("@noble/hashes/sha256");
+const request_1 = require("./request");
+/** Same bucketing as the server: the same subject lands in the same bucket everywhere. */
+function bucket(flagKey, subjectKey) {
+    const d = (0, sha256_1.sha256)(new TextEncoder().encode(`${flagKey}:${subjectKey}`));
+    return (((d[0] << 24) | (d[1] << 16) | (d[2] << 8) | d[3]) >>> 0) % 100;
+}
+/** Evaluate a flag definition for a subject (first matching in-bucket rule wins, else the default). */
+function evaluateFeatureFlag(flag, subject) {
+    if (!flag.enabled)
+        return flag.off_value;
+    const seed = subject.user_id ?? subject.org_id ?? '';
+    for (const rule of flag.rules) {
+        const m = rule.match ?? {};
+        if (m.user_ids && (!subject.user_id || !m.user_ids.includes(subject.user_id)))
+            continue;
+        if (m.org_ids && (!subject.org_id || !m.org_ids.includes(subject.org_id)))
+            continue;
+        if (m.plans && (!subject.plan || !m.plans.includes(subject.plan)))
+            continue;
+        if (rule.percentage !== undefined && (!seed || bucket(flag.key, seed) >= rule.percentage))
+            continue;
+        return rule.value;
+    }
+    return flag.default_value;
+}
+const pageAll = async (request) => {
+    const out = [];
+    let after;
+    for (;;) {
+        const page = await request({
+            method: 'GET',
+            path: '/v1/feature_flags',
+            query: { limit: 200, starting_after: after },
+        });
+        out.push(...page.data);
+        if (!page.has_more || page.data.length === 0)
+            return out;
+        after = page.data[page.data.length - 1].key;
+    }
+};
+function flagsResource(request, cacheTtlMs = 30_000) {
+    let cache;
+    let inflight;
+    /** All flag definitions, cached for `cacheTtlMs`; concurrent callers share one fetch. */
+    const definitions = async () => {
+        if (cache && Date.now() - cache.at < cacheTtlMs)
+            return cache.flags;
+        inflight ??= pageAll(request)
+            .then((all) => {
+            cache = { at: Date.now(), flags: new Map(all.map((f) => [f.key, f])) };
+            return cache.flags;
+        })
+            .finally(() => { inflight = undefined; });
+        return inflight;
+    };
+    return {
+        create(body, idempotencyKey) {
+            return request({ method: 'POST', path: '/v1/feature_flags', body, idempotencyKey });
+        },
+        /** `starting_after` is the key of the last flag of the previous page. */
+        list(params = {}) {
+            return request({ method: 'GET', path: '/v1/feature_flags', query: params });
+        },
+        retrieve(key) {
+            return request({ method: 'GET', path: `/v1/feature_flags/${(0, request_1.enc)(key)}` });
+        },
+        update(key, body) {
+            return request({ method: 'PATCH', path: `/v1/feature_flags/${(0, request_1.enc)(key)}`, body });
+        },
+        delete(key) {
+            return request({ method: 'DELETE', path: `/v1/feature_flags/${(0, request_1.enc)(key)}` });
+        },
+        /** Server-side evaluation; `plan` defaults to the org's (else the user's) resolved plan. */
+        evaluate(body) {
+            return request({ method: 'POST', path: '/v1/feature_flags/evaluate', body });
+        },
+        /** Local evaluation against cached definitions. `plan` is not looked up here — pass it for plan rules. */
+        async get(key, subject, fallback) {
+            const flag = (await definitions()).get(key);
+            return flag ? evaluateFeatureFlag(flag, subject) : fallback;
+        },
+        /** True only for a boolean flag that evaluates to true; an unknown flag is false. */
+        async isEnabled(key, subject = {}) {
+            return (await this.get(key, subject, false)) === true;
+        },
+        /** Drop the cached definitions (e.g. after changing a flag). */
+        invalidate() {
+            cache = undefined;
+        },
+        /** Replace the entitlements assigned to an organization (an empty body clears them). */
+        assignOrganizationEntitlements(orgId, body) {
+            return request({ method: 'PUT', path: `/v1/organizations/${(0, request_1.enc)(orgId)}/entitlements`, body });
+        },
+        assignUserEntitlements(userId, body) {
+            return request({ method: 'PUT', path: `/v1/users/${(0, request_1.enc)(userId)}/entitlements`, body });
+        },
+    };
+}
+//# sourceMappingURL=flags.js.map

package/dist/client/flags.js.map

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

package/dist/client/groups.d.ts

@@ -0,0 +1,146 @@
+import { type RequestFn } from './request';
+import type { ListPage } from './types';
+/**
+ * Instance-level groups (independent of organizations) and the rules engine.
+ * Groups nest, carry attributes, map to app roles, can ride the session token as
+ * `groups`, and fill by hand, by filter, from SSO claims or by rules.
+ */
+export interface Group {
+    object: 'group';
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    parent_id: string | null;
+    attributes: Record<string, unknown>;
+    app_role_keys: string[];
+    include_in_token: boolean;
+    dynamic_filter: Record<string, unknown> | null;
+    sso_match: {
+        claim: string;
+        equals?: string;
+        contains?: string;
+        matches?: string;
+    } | null;
+    member_count?: number;
+    /** `users.groups` only: how the user joined. */
+    source?: 'manual' | 'dynamic' | 'sso' | 'rule';
+    created_at: number;
+    updated_at: number;
+}
+export interface GroupBody {
+    slug?: string;
+    name?: string;
+    description?: string | null;
+    parent_id?: string | null;
+    attributes?: Record<string, unknown>;
+    app_role_keys?: string[];
+    include_in_token?: boolean;
+    /** A user-search filter tree. */
+    dynamic_filter?: Record<string, unknown> | null;
+    sso_match?: Group['sso_match'];
+}
+export interface GroupMember {
+    object: 'group_member';
+    group_id: string;
+    user_id: string;
+    source: 'manual' | 'dynamic' | 'sso' | 'rule';
+    source_ref: string | null;
+    created_at: number;
+}
+export type GroupRuleAction = {
+    type: 'add_to_group';
+    group: string;
+} | {
+    type: 'add_app_role';
+    role: string;
+} | {
+    type: 'set_trait';
+    key: string;
+    value: unknown;
+};
+export interface GroupRule {
+    object: 'group_rule';
+    id: string;
+    name: string;
+    enabled: boolean;
+    priority: number;
+    condition: Record<string, unknown>;
+    actions: GroupRuleAction[];
+    created_by: string | null;
+    created_at: number;
+    updated_at: number;
+}
+export interface GroupRuleBody {
+    name?: string;
+    enabled?: boolean;
+    priority?: number;
+    condition?: Record<string, unknown>;
+    actions?: GroupRuleAction[];
+}
+export interface GroupRuleResult {
+    object: 'group_rule_result';
+    rule_id: string;
+    matched: number;
+    groups_added: number;
+    groups_removed: number;
+    roles_granted: number;
+    traits_set: number;
+}
+export declare function groupsResource(request: RequestFn): {
+    list(): Promise<ListPage<Group>>;
+    get(idOrSlug: string): Promise<Group>;
+    create(body: GroupBody & {
+        slug: string;
+        name: string;
+    }, idempotencyKey?: string): Promise<Group>;
+    update(idOrSlug: string, body: GroupBody): Promise<Group>;
+    delete(idOrSlug: string): Promise<{
+        object: "group";
+        id: string;
+        deleted: true;
+    }>;
+    listMembers(idOrSlug: string, query?: {
+        limit?: number;
+        starting_after?: string;
+    }): Promise<ListPage<GroupMember> & {
+        next_cursor: string | null;
+    }>;
+    /** Add up to 500 users by hand. */
+    addMembers(idOrSlug: string, userIds: string[]): Promise<{
+        added: number;
+        promoted: number;
+        already_member: number;
+        skipped: number;
+    }>;
+    removeMembers(idOrSlug: string, userIds: string[]): Promise<{
+        removed: number;
+    }>;
+    /** Re-evaluate a dynamic group's filter now. */
+    reapply(idOrSlug: string): Promise<{
+        matched: number;
+        added: number;
+        removed: number;
+    }>;
+    /** A user's direct groups. */
+    forUser(userId: string): Promise<ListPage<Group>>;
+    rules: {
+        list(): Promise<ListPage<GroupRule>>;
+        get(id: string): Promise<GroupRule>;
+        create(body: GroupRuleBody & {
+            name: string;
+            condition: Record<string, unknown>;
+            actions: GroupRuleAction[];
+        }, idempotencyKey?: string): Promise<GroupRule>;
+        update(id: string, body: GroupRuleBody): Promise<GroupRule>;
+        delete(id: string): Promise<{
+            object: "group_rule";
+            id: string;
+            deleted: true;
+        }>;
+        /** Run one rule now. */
+        apply(id: string): Promise<GroupRuleResult>;
+        /** Run every enabled rule in priority order. */
+        applyAll(): Promise<ListPage<GroupRuleResult>>;
+    };
+};