@meowpanel/api 0.2.0 → 0.4.0

package/script/src/resources/users.d.ts

@@ -0,0 +1,330 @@
+import type { HttpClient } from '../http.js';
+import { ResourceNamespace } from '../namespace.js';
+import { ReactiveResource } from '../reactive.js';
+import type { IncludeOptions, ResourceColor, ResourceWith } from '../types.js';
+import { type ISODate, type NanoID, type Paginated } from '../types.js';
+import { type PermissionGrant, type PermissionGrantInput } from './permissions.js';
+/** A UI theme preference. */
+export type UiTheme = 'system' | 'dark' | 'light';
+/** Raw API shape for a user's preferences. @internal */
+export interface UserPreferencesData {
+    theme: UiTheme;
+    language: string | null;
+}
+/** Raw API shape for a user's identifiers. @internal */
+export interface UserIdentifiersData {
+    password: {
+        created_at: ISODate;
+        last_used_at: ISODate | null;
+    } | null;
+    whmcs: {
+        whmcs_id: string;
+        email: string;
+        name: string;
+        sync_email: boolean;
+        sync_nickname: boolean;
+        last_used_at: ISODate | null;
+        created_at: ISODate;
+        updated_at: ISODate;
+    } | null;
+}
+/**
+ * Raw API response shape for a user.
+ *
+ * A direct `/users` response carries a bare `id`. When the same user is
+ * expanded as an issuer reference (e.g. an `owner`), `id` is the namespaced
+ * `"user:<id>"` form and `ref_id` holds the bare id.
+ * @internal
+ */
+export interface UserData {
+    id: string;
+    type?: string;
+    ref_id?: string;
+    email: string;
+    email_verified_at?: ISODate | null;
+    nickname: string | null;
+    avatar_uri: string | null;
+    disabled_at?: ISODate | null;
+    preferences?: UserPreferencesData | null;
+    permissions?: string[];
+    identifiers?: UserIdentifiersData | null;
+    created_at: ISODate;
+    updated_at: ISODate;
+}
+/** Display and locale preferences for a user. */
+export interface UserPreferences {
+    /** The user's preferred UI theme. */
+    theme: UiTheme;
+    /** The user's preferred UI language code, or `null` to follow the default. */
+    language: string | null;
+}
+/** The password identifier on a user. */
+export interface UserPasswordIdentifier {
+    /** When the password was first set. */
+    createdAt: Date;
+    /** When the password was last used to log in, or `null`. */
+    lastUsedAt: Date | null;
+}
+/** The WHMCS link on a user. */
+export interface UserWhmcsIdentifier {
+    /** The linked WHMCS client UUID. */
+    whmcsId: string;
+    /** Email cached from WHMCS. */
+    email: string;
+    /** Name cached from WHMCS. */
+    name: string;
+    /** Whether WHMCS email changes sync to the account. */
+    syncEmail: boolean;
+    /** Whether WHMCS name changes sync to the nickname. */
+    syncNickname: boolean;
+    /** When this link was last used to log in, or `null`. */
+    lastUsedAt: Date | null;
+    /** When this link was created. */
+    createdAt: Date;
+    /** When this link was last updated. */
+    updatedAt: Date;
+}
+/** A user's external identifiers. Requires `?include=identifiers`. */
+export interface UserIdentifiers {
+    /** The password identifier, or `null` if the user has no password. */
+    password: UserPasswordIdentifier | null;
+    /** The WHMCS link, or `null` if the user is not linked. */
+    whmcs: UserWhmcsIdentifier | null;
+}
+/**
+ * A MeowPanel user account.
+ *
+ * Retrieved via {@link UsersNamespace.get} or {@link UsersNamespace.list}.
+ */
+export declare class User extends ReactiveResource {
+    /** The user's unique NanoID. */
+    readonly id: NanoID;
+    /** The issuer type, `'user'` for user accounts. */
+    issuerType: string;
+    /** The user's login email address. */
+    email: string;
+    /** When the user verified their email, or `null` if unverified. */
+    emailVerifiedAt: Date | null;
+    /** The user's display nickname. */
+    nickname: string | null;
+    /** URL of the user's avatar image, or `null` if no avatar is set. */
+    avatarUri: string | null;
+    /** When the user account was disabled, or `null` if active. */
+    disabledAt: Date | null;
+    /** Display and locale preferences. Requires `?include=preferences`. */
+    preferences: UserPreferences | null | undefined;
+    /** The user's assigned permission scopes. Requires `?include=permissions`. */
+    permissions: string[] | undefined;
+    /** The user's external identifiers. Requires `?include=identifiers`. */
+    identifiers: UserIdentifiers | undefined;
+    /** When this user account was created. */
+    createdAt: Date;
+    /** When this user account was last updated. */
+    updatedAt: Date;
+    /** @internal */
+    constructor(data: UserData);
+    /**
+     * Apply raw API data to this user instance, updating all mutable fields.
+     *
+     * Called by the constructor and by {@link UsersNamespace.update} to update the instance in-place.
+     */
+    applyData(data: UserData): void;
+}
+/** Fields accepted when creating a user. */
+export interface CreateUserPayload {
+    /** Login email address. */
+    email: string;
+    /** Display nickname. */
+    nickname?: string;
+    /** Mark the email as already verified. */
+    emailVerified?: boolean;
+    /** Link a WHMCS client at creation time. */
+    whmcs?: {
+        id: string;
+        name: string;
+    };
+}
+/** Fields that can be updated on a user. All fields are optional. */
+export interface UpdateUserPayload {
+    /** New email address for the user. */
+    email?: string;
+    /** New display nickname. */
+    nickname?: string;
+    /** Preference updates (shallow-merged). */
+    preferences?: {
+        /** UI theme. */
+        theme?: UiTheme;
+        /** UI language code, or `null` to clear. */
+        language?: string | null;
+    };
+}
+/** Result of syncing a WHMCS-linked user. */
+export interface WhmcsSyncResult {
+    /** The updated user. */
+    user: User;
+    /** Fields that were not propagated to the account (sync disabled or overridden). */
+    skipped: string[];
+}
+/** Valid include keys for user endpoints. */
+export type UserInclude = 'preferences' | 'permissions' | 'identifiers';
+/** Maps each {@link UserInclude} key to the field(s) it guarantees on the {@link User} instance. */
+interface UserIncludeMap {
+    preferences: {
+        preferences: UserPreferences | null;
+    };
+    permissions: {
+        permissions: string[];
+    };
+    identifiers: {
+        identifiers: UserIdentifiers;
+    };
+}
+/** A {@link User} with specific include fields guaranteed to be populated. */
+export type UserWith<I extends readonly UserInclude[] = []> = ResourceWith<User, UserIncludeMap, I>;
+/** Typed events emitted by {@link UsersNamespace}. */
+export interface UserEvents {
+    /** Fired after a user is created. */
+    created: User;
+    /** Fired after a user is successfully updated. */
+    updated: User;
+}
+/** A role assigned to a user, with its assignment order and scope. */
+export interface UserRoleAssignment {
+    /** The role's NanoID. */
+    id: NanoID;
+    /** The role title. */
+    title: string;
+    /** The role description. */
+    description: string | null;
+    /** The role color. */
+    color: ResourceColor | null;
+    /** The assignment's sort order, or `null`. */
+    order: number | null;
+    /** The namespaced scope the assignment is narrowed to, or `null` for all. */
+    scope: string | null;
+}
+/** A role to assign to a user. */
+export interface AssignRoleInput {
+    /** The role's NanoID. */
+    roleId: NanoID;
+    /** Narrow every permission the role confers to this namespaced scope (`"<type>:<id>"`). */
+    scope?: string;
+    /** Sort order for the assignment; must be unique per user. */
+    order?: number;
+}
+/**
+ * Manages a user's role assignments.
+ *
+ * Access via `api.users.roles(userId)`.
+ */
+export declare class UserRolesManager {
+    private readonly userId;
+    private readonly http;
+    /** @internal */
+    constructor(userId: NanoID, http: HttpClient);
+    /** List the roles assigned to the user. */
+    list(): Promise<UserRoleAssignment[]>;
+    /** Assign one or more roles to the user. */
+    assign(roles: AssignRoleInput | AssignRoleInput[]): Promise<void>;
+    /** Remove a role from the user. */
+    remove(roleId: NanoID): Promise<void>;
+    /** Change a role assignment's sort order. */
+    setOrder(roleId: NanoID, order: number): Promise<void>;
+}
+/**
+ * Manages a user's direct permission grants.
+ *
+ * Access via `api.users.permissions(userId)`.
+ */
+export declare class UserPermissionsManager {
+    private readonly userId;
+    private readonly http;
+    /** @internal */
+    constructor(userId: NanoID, http: HttpClient);
+    /** List the user's direct permission grants. */
+    list(): Promise<PermissionGrant[]>;
+    /**
+     * Grant one or more permissions to the user.
+     *
+     * You cannot grant a permission you do not hold yourself at the target scope.
+     */
+    grant(grants: PermissionGrantInput | PermissionGrantInput[]): Promise<void>;
+    /**
+     * Revoke a permission from the user.
+     *
+     * @param permission The permission name to revoke.
+     * @param scope      The namespaced scope (`"<type>:<id>"`) to revoke at, or omit for the global grant.
+     */
+    revoke(permission: string, scope?: string): Promise<void>;
+}
+/**
+ * Namespace for user management.
+ *
+ * Access via `api.users`.
+ *
+ * @example
+ * ```ts ignore
+ * const users = await api.users.list();
+ * const user = await api.users.get(id);
+ * await api.users.update(id, { nickname: 'newname' });
+ * ```
+ */
+export declare class UsersNamespace extends ResourceNamespace<User, UserEvents> {
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Fetch a paginated list of all users.
+     *
+     * @param opts Pagination, search, and include options.
+     */
+    list<const I extends readonly UserInclude[] = []>(opts?: {
+        page?: number;
+        perPage?: number;
+        search?: string;
+    } & IncludeOptions<UserInclude, I>): Promise<Paginated<UserWith<I>>>;
+    /**
+     * Fetch a single user by ID.
+     *
+     * @param id   The user's NanoID.
+     * @param opts Include options.
+     */
+    get<const I extends readonly UserInclude[] = []>(id: NanoID, opts?: IncludeOptions<UserInclude, I>): Promise<UserWith<I>>;
+    /** Create a user. */
+    create(payload: CreateUserPayload): Promise<User>;
+    /**
+     * Update a user's profile fields.
+     *
+     * @param id      The user's NanoID.
+     * @param payload The fields to update.
+     */
+    update(id: NanoID, payload: UpdateUserPayload): Promise<User>;
+    /** Disable a user, blocking them from authenticating. */
+    disable(id: NanoID): Promise<void>;
+    /** Re-enable a disabled user. */
+    enable(id: NanoID): Promise<void>;
+    /**
+     * Propagate WHMCS-sourced changes to the linked user.
+     *
+     * @param whmcsId The linked WHMCS client UUID.
+     * @param payload The WHMCS-side email and/or name.
+     */
+    syncWhmcs(whmcsId: string, payload: {
+        email?: string;
+        name?: string;
+    }): Promise<WhmcsSyncResult>;
+    /**
+     * Unlink a WHMCS-linked user.
+     *
+     * @param whmcsId The linked WHMCS client UUID.
+     * @param opts    `unlink: true` only removes the link; otherwise the user is also disabled.
+     */
+    unlinkWhmcs(whmcsId: string, opts?: {
+        unlink?: boolean;
+    }): Promise<User>;
+    /** Manage a user's role assignments. */
+    roles(userId: NanoID): UserRolesManager;
+    /** Manage a user's direct permission grants. */
+    permissions(userId: NanoID): UserPermissionsManager;
+}
+export {};
+//# sourceMappingURL=users.d.ts.map

package/script/src/resources/users.d.ts.map

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

package/script/src/resources/users.js

@@ -0,0 +1,287 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsersNamespace = exports.UserPermissionsManager = exports.UserRolesManager = exports.User = void 0;
+const namespace_js_1 = require("../namespace.js");
+const reactive_js_1 = require("../reactive.js");
+const types_js_1 = require("../types.js");
+const permissions_js_1 = require("./permissions.js");
+/**
+ * A MeowPanel user account.
+ *
+ * Retrieved via {@link UsersNamespace.get} or {@link UsersNamespace.list}.
+ */
+class User extends reactive_js_1.ReactiveResource {
+    /** The user's unique NanoID. */
+    id;
+    /** The issuer type, `'user'` for user accounts. */
+    issuerType;
+    /** The user's login email address. */
+    email;
+    /** When the user verified their email, or `null` if unverified. */
+    emailVerifiedAt;
+    /** The user's display nickname. */
+    nickname;
+    /** URL of the user's avatar image, or `null` if no avatar is set. */
+    avatarUri;
+    /** When the user account was disabled, or `null` if active. */
+    disabledAt;
+    /** Display and locale preferences. Requires `?include=preferences`. */
+    preferences;
+    /** The user's assigned permission scopes. Requires `?include=permissions`. */
+    permissions;
+    /** The user's external identifiers. Requires `?include=identifiers`. */
+    identifiers;
+    /** When this user account was created. */
+    createdAt;
+    /** When this user account was last updated. */
+    updatedAt;
+    /** @internal */
+    constructor(data) {
+        super();
+        this.id = data.ref_id ? (0, types_js_1.toNanoID)(data.ref_id) : (0, types_js_1.parseIssuerRef)(data.id).id;
+        this.applyData(data);
+    }
+    /**
+     * Apply raw API data to this user instance, updating all mutable fields.
+     *
+     * Called by the constructor and by {@link UsersNamespace.update} to update the instance in-place.
+     */
+    applyData(data) {
+        this.issuerType = data.type ?? 'user';
+        this.email = data.email;
+        this.emailVerifiedAt = data.email_verified_at ? new Date(data.email_verified_at) : null;
+        this.nickname = data.nickname;
+        this.avatarUri = data.avatar_uri;
+        this.disabledAt = data.disabled_at ? new Date(data.disabled_at) : null;
+        this.preferences = data.preferences ?? undefined;
+        this.permissions = data.permissions;
+        this.identifiers = data.identifiers ? parseIdentifiers(data.identifiers) : undefined;
+        this.createdAt = new Date(data.created_at);
+        this.updatedAt = new Date(data.updated_at);
+        this.notify();
+    }
+}
+exports.User = User;
+function parseIdentifiers(data) {
+    return {
+        password: data.password
+            ? {
+                createdAt: new Date(data.password.created_at),
+                lastUsedAt: data.password.last_used_at ? new Date(data.password.last_used_at) : null,
+            }
+            : null,
+        whmcs: data.whmcs
+            ? {
+                whmcsId: data.whmcs.whmcs_id,
+                email: data.whmcs.email,
+                name: data.whmcs.name,
+                syncEmail: data.whmcs.sync_email,
+                syncNickname: data.whmcs.sync_nickname,
+                lastUsedAt: data.whmcs.last_used_at ? new Date(data.whmcs.last_used_at) : null,
+                createdAt: new Date(data.whmcs.created_at),
+                updatedAt: new Date(data.whmcs.updated_at),
+            }
+            : null,
+    };
+}
+/**
+ * Manages a user's role assignments.
+ *
+ * Access via `api.users.roles(userId)`.
+ */
+class UserRolesManager {
+    userId;
+    http;
+    /** @internal */
+    constructor(userId, http) {
+        this.userId = userId;
+        this.http = http;
+    }
+    /** List the roles assigned to the user. */
+    async list() {
+        const data = await this.http.get(`/users/${this.userId}/roles`);
+        return data.map((d) => ({
+            id: (0, types_js_1.toNanoID)(d.id),
+            title: d.title,
+            description: d.description,
+            color: d.color,
+            order: d.order,
+            scope: d.scope,
+        }));
+    }
+    /** Assign one or more roles to the user. */
+    async assign(roles) {
+        const body = (Array.isArray(roles) ? roles : [roles]).map((r) => ({
+            role_id: r.roleId,
+            scope: r.scope,
+            order: r.order,
+        }));
+        await this.http.post(`/users/${this.userId}/roles`, body);
+    }
+    /** Remove a role from the user. */
+    async remove(roleId) {
+        await this.http.delete(`/users/${this.userId}/roles/${roleId}`);
+    }
+    /** Change a role assignment's sort order. */
+    async setOrder(roleId, order) {
+        await this.http.patch(`/users/${this.userId}/roles/${roleId}`, { order });
+    }
+}
+exports.UserRolesManager = UserRolesManager;
+/**
+ * Manages a user's direct permission grants.
+ *
+ * Access via `api.users.permissions(userId)`.
+ */
+class UserPermissionsManager {
+    userId;
+    http;
+    /** @internal */
+    constructor(userId, http) {
+        this.userId = userId;
+        this.http = http;
+    }
+    /** List the user's direct permission grants. */
+    async list() {
+        const data = await this.http.get(`/users/${this.userId}/permissions`);
+        return data.map(permissions_js_1.parseGrant);
+    }
+    /**
+     * Grant one or more permissions to the user.
+     *
+     * You cannot grant a permission you do not hold yourself at the target scope.
+     */
+    async grant(grants) {
+        await this.http.post(`/users/${this.userId}/permissions`, (0, permissions_js_1.grantsToBody)(grants));
+    }
+    /**
+     * Revoke a permission from the user.
+     *
+     * @param permission The permission name to revoke.
+     * @param scope      The namespaced scope (`"<type>:<id>"`) to revoke at, or omit for the global grant.
+     */
+    async revoke(permission, scope) {
+        const params = scope ? { scope } : undefined;
+        await this.http.delete(`/users/${this.userId}/permissions/${encodeURIComponent(permission)}`, { params });
+    }
+}
+exports.UserPermissionsManager = UserPermissionsManager;
+/**
+ * Namespace for user management.
+ *
+ * Access via `api.users`.
+ *
+ * @example
+ * ```ts ignore
+ * const users = await api.users.list();
+ * const user = await api.users.get(id);
+ * await api.users.update(id, { nickname: 'newname' });
+ * ```
+ */
+class UsersNamespace extends namespace_js_1.ResourceNamespace {
+    /** @internal */
+    constructor(http) {
+        super(http);
+    }
+    /**
+     * Fetch a paginated list of all users.
+     *
+     * @param opts Pagination, search, and include options.
+     */
+    async list(opts = {}) {
+        const extra = {};
+        const include = (0, types_js_1.joinIncludes)(opts);
+        if (include)
+            extra['include'] = include;
+        const result = await this.http.list('/users', opts, extra);
+        const users = result.data.map((d) => new User(d));
+        this.setCache(users);
+        return { ...result, data: users };
+    }
+    /**
+     * Fetch a single user by ID.
+     *
+     * @param id   The user's NanoID.
+     * @param opts Include options.
+     */
+    async get(id, opts = {}) {
+        const params = {};
+        const include = (0, types_js_1.joinIncludes)(opts);
+        if (include)
+            params['include'] = include;
+        const data = await this.http.get(`/users/${id}`, { params });
+        return new User(data);
+    }
+    /** Create a user. */
+    async create(payload) {
+        const body = {
+            email: payload.email,
+            nickname: payload.nickname,
+            email_verified: payload.emailVerified,
+            identifiers: payload.whmcs ? { whmcs: { id: payload.whmcs.id, name: payload.whmcs.name } } : undefined,
+        };
+        const data = await this.http.post('/users', body);
+        const user = new User(data);
+        this.addToCache(user);
+        this.emit('created', user);
+        return user;
+    }
+    /**
+     * Update a user's profile fields.
+     *
+     * @param id      The user's NanoID.
+     * @param payload The fields to update.
+     */
+    async update(id, payload) {
+        const data = await this.http.patch(`/users/${id}`, payload);
+        const existing = this.cache.find((u) => u.id === id);
+        if (existing) {
+            existing.applyData(data);
+            this.upsertCache(existing);
+            this.emit('updated', existing);
+            return existing;
+        }
+        const user = new User(data);
+        this.upsertCache(user);
+        this.emit('updated', user);
+        return user;
+    }
+    /** Disable a user, blocking them from authenticating. */
+    async disable(id) {
+        await this.http.post(`/users/${id}/disable`);
+    }
+    /** Re-enable a disabled user. */
+    async enable(id) {
+        await this.http.post(`/users/${id}/enable`);
+    }
+    /**
+     * Propagate WHMCS-sourced changes to the linked user.
+     *
+     * @param whmcsId The linked WHMCS client UUID.
+     * @param payload The WHMCS-side email and/or name.
+     */
+    async syncWhmcs(whmcsId, payload) {
+        const data = await this.http.patch(`/users/whmcs/${encodeURIComponent(whmcsId)}`, payload);
+        return { user: new User(data.user), skipped: data.skipped };
+    }
+    /**
+     * Unlink a WHMCS-linked user.
+     *
+     * @param whmcsId The linked WHMCS client UUID.
+     * @param opts    `unlink: true` only removes the link; otherwise the user is also disabled.
+     */
+    async unlinkWhmcs(whmcsId, opts = {}) {
+        const params = opts.unlink ? { unlink: 'true' } : undefined;
+        const data = await this.http.delete(`/users/whmcs/${encodeURIComponent(whmcsId)}`, { params });
+        return new User(data);
+    }
+    /** Manage a user's role assignments. */
+    roles(userId) {
+        return new UserRolesManager(userId, this.http);
+    }
+    /** Manage a user's direct permission grants. */
+    permissions(userId) {
+        return new UserPermissionsManager(userId, this.http);
+    }
+}
+exports.UsersNamespace = UsersNamespace;

package/script/src/types.d.ts

@@ -22,6 +22,23 @@ export type NanoID = string & {
 export declare function toNanoID(raw: string): NanoID;
 /** ISO 8601 date-time string as returned by the MeowPanel API, e.g. `"2024-01-15T12:00:00.000Z"`. */
 export type ISODate = string;
+/** A UI color label used for visual grouping (hosts, roles). */
+export type ResourceColor = 'red' | 'orange' | 'yellow' | 'green' | 'blue' | 'purple' | 'pink' | 'brown' | 'black' | 'white';
+/** A namespaced issuer reference, e.g. `"user:abc123def456"`. */
+export type IssuerRef = string;
+/** The parsed parts of an {@link IssuerRef}. */
+export interface ParsedIssuer {
+    /** The issuer type token, e.g. `"user"`, `"system"`, `"api_key"`, `"node"`. */
+    type: string;
+    /** The bare resource NanoID. */
+    id: NanoID;
+}
+/**
+ * Split a namespaced issuer reference (`"<type>:<id>"`) into its type and bare id.
+ *
+ * A bare id with no prefix yields an empty `type`.
+ */
+export declare function parseIssuerRef(ref: string): ParsedIssuer;
 /** Options for paginated list requests. */
 export interface ListOptions {
     /** Page number (1-based). Defaults to 1. */
@@ -122,5 +139,5 @@ export type ServerRestrictedState = 'installing' | 'install_failed' | 'restoring
 /**
  * An SFTP permission scope that can be assigned to a path pattern for an SFTP user.
  */
-export type SftpPermission = 'sftp.content.list' | 'sftp.content.read' | 'sftp.content.create' | 'sftp.content.manage' | 'sftp.content.delete';
+export type SftpPermission = 'server.file.list' | 'server.file.read' | 'server.file.create' | 'server.file.manage' | 'server.file.delete';
 //# sourceMappingURL=types.d.ts.map

package/script/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAEnE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,qGAAqG;AACrG,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC3B,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC3B,qCAAqC;IACrC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,wEAAwE;AACxE,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,IAAI,GAAG,CAAC,GAC/G,KAAK,CAAC;AAET;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,CACvB,CAAC,EACD,UAAU,EACV,CAAC,SAAS,SAAS,CAAC,MAAM,UAAU,CAAC,EAAE,GAAG,EAAE,IAE1C,CAAC,GACD,mBAAmB,CACpB,CAAC,CAAC,MAAM,CAAC,SAAS,MAAM,CAAC,GAAG,CAAC,SAAS,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,KAAK,CACtF,CAAC;AAEH;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,OAAO,SAAS,MAAM,EAAE,CAAC,SAAS,SAAS,OAAO,EAAE,GAAG,EAAE;IACxF;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CAG7G;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAEhE;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,CAAC;AAEjG;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAC9B,YAAY,GACZ,gBAAgB,GAChB,kBAAkB,GAClB,aAAa,GACb,cAAc,GACd,YAAY,GACZ,SAAS,GACT,SAAS,GACT,IAAI,CAAC;AAER;;GAEG;AACH,MAAM,MAAM,cAAc,GACvB,mBAAmB,GACnB,mBAAmB,GACnB,qBAAqB,GACrB,qBAAqB,GACrB,qBAAqB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/src/types.ts"],"names":[],"mappings":"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"}