@meowpanel/api 0.1.0-alpha.11 → 1.0.0-beta.2

package/script/src/resources/account.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountResource = exports.ApiKeyAccount = exports.UserAccount = exports.Account = void 0;
+const reactive_js_1 = require("../reactive.js");
+const types_js_1 = require("../types.js");
+/**
+ * Base class for the authenticated account.
+ *
+ * Use {@link isUser} / {@link isApiKey} to narrow to the specific subclass.
+ */
+class Account extends reactive_js_1.ReactiveResource {
+    http;
+    id;
+    permissions;
+    createdAt;
+    updatedAt;
+    /** @internal */
+    constructor(data, http) {
+        super();
+        this.http = http;
+        this.id = (0, types_js_1.toNanoID)(data.id);
+        this.permissions = data.permissions;
+        this.createdAt = new Date(data.created_at);
+        this.updatedAt = new Date(data.updated_at);
+    }
+    isUser() {
+        return this.issuerType === 'user';
+    }
+    isApiKey() {
+        return this.issuerType === 'api_key';
+    }
+    /** @internal */
+    static create(data, http) {
+        switch (data.issuer_type) {
+            case 'user':
+                return new UserAccount(data, http);
+            case 'api_key':
+                return new ApiKeyAccount(data, http);
+            default:
+                throw new Error(`Unknown account issuer type: ${data.issuer_type}`);
+        }
+    }
+}
+exports.Account = Account;
+/** A human user account. */
+class UserAccount extends Account {
+    issuerType = 'user';
+    email;
+    nickname;
+    avatarUri;
+    /**
+     * Display preferences. Populated with `include=display`.
+     * Requires `member.display.read` permission or being the account owner.
+     */
+    display;
+    /** @internal */
+    constructor(data, http) {
+        super(data, http);
+        this.email = data.email;
+        this.nickname = data.nickname;
+        this.avatarUri = data.avatar_uri;
+        this.display = data.display ?? undefined;
+    }
+    /** Update this user account in place. */
+    async update(payload) {
+        await this.http.patch('/account', payload);
+        const data = await this.http.get('/account');
+        this.email = data.email;
+        this.nickname = data.nickname;
+        this.avatarUri = data.avatar_uri;
+        this.display = data.display ?? undefined;
+        this.permissions = data.permissions;
+        this.createdAt = new Date(data.created_at);
+        this.updatedAt = new Date(data.updated_at);
+        this.notify();
+    }
+    /** Fetch the avatar image as a Blob. */
+    async fetchAvatar() {
+        const res = await this.http.fetch('/account/avatar', { method: 'GET' });
+        return await res.blob();
+    }
+}
+exports.UserAccount = UserAccount;
+/** An API key credential. */
+class ApiKeyAccount extends Account {
+    issuerType = 'api_key';
+    name;
+    description;
+    ownerId;
+    /** The owner user. */
+    owner;
+    /** @internal */
+    constructor(data, http) {
+        super(data, http);
+        this.name = data.name;
+        this.description = data.description;
+        this.ownerId = (0, types_js_1.toNanoID)(data.owner_id);
+        this.owner = data.owner ? new UserAccount(data.owner, http) : undefined;
+    }
+}
+exports.ApiKeyAccount = ApiKeyAccount;
+/**
+ * Resource for the currently authenticated account.
+ *
+ * Access via `api.account`.
+ *
+ * @example
+ * ```ts ignore
+ * const me = await api.account.get();
+ * if (me.isUser()) {
+ *   console.log(me.nickname, me.email);
+ *   await me.update({ display: { theme: 'dark' } });
+ * } else {
+ *   console.log('API key:', me.name, 'owner:', me.ownerId);
+ * }
+ * ```
+ */
+class AccountResource {
+    http;
+    /** @internal */
+    constructor(http) {
+        this.http = http;
+    }
+    /** Fetch the currently authenticated account. */
+    async get(opts = {}) {
+        const params = {};
+        const include = (0, types_js_1.joinIncludes)(opts);
+        if (include)
+            params['include'] = include;
+        const data = await this.http.get('/account', { params });
+        return Account.create(data, this.http);
+    }
+    /** Update the current user account. Only works for user accounts. */
+    async update(payload) {
+        await this.http.patch('/account', payload);
+        const data = await this.http.get('/account');
+        return new UserAccount(data, this.http);
+    }
+    /** Upload a new avatar image. Only works for user accounts. */
+    async uploadAvatar(image, contentType) {
+        const body = image instanceof Blob ? image : new Blob([image], { type: contentType });
+        await this.http.fetch('/account/avatar', {
+            method: 'POST',
+            body,
+            headers: { 'Content-Type': contentType },
+        });
+    }
+    /** Fetch the current account avatar image. */
+    async fetchAvatar() {
+        const res = await this.http.fetch('/account/avatar', { method: 'GET' });
+        return await res.blob();
+    }
+    /** Fetch the permission scopes available to the current account. */
+    scopes() {
+        return this.http.get('/account/scopes');
+    }
+}
+exports.AccountResource = AccountResource;

package/script/src/resources/api-keys.d.ts

@@ -0,0 +1,116 @@
+import type { HttpClient } from '../http.js';
+import { ResourceNamespace } from '../namespace.js';
+import { ReactiveResource } from '../reactive.js';
+import { type ISODate, type NanoID, type Paginated } from '../types.js';
+/** Raw API shape for an API key. @internal */
+interface ApiKeyData {
+    id: string;
+    name: string;
+    description?: string | null;
+    /** Only returned once, at creation time. */
+    token?: string;
+    last_used_at?: ISODate | null;
+    created_at: ISODate;
+    updated_at?: ISODate;
+}
+/**
+ * An API key credential for authenticating programmatic access to the MeowPanel API.
+ *
+ * Retrieved via {@link ApiKeysNamespace.list} or {@link ApiKeysNamespace.create}.
+ *
+ * > **Note:** The `token` field is only populated when the key is first created.
+ * > It cannot be retrieved again after that. Store it securely.
+ */
+export declare class ApiKey extends ReactiveResource {
+    /** The API key's unique NanoID. */
+    readonly id: NanoID;
+    /** Display name for this API key. */
+    name: string;
+    /** Optional description for this API key. */
+    description: string | null | undefined;
+    /**
+     * The bearer token value.
+     *
+     * Only populated immediately after creation via {@link ApiKeysNamespace.create}.
+     * `undefined` on all subsequent fetches - store it securely when first received.
+     */
+    token: string | undefined;
+    /** When this key was last used to authenticate a request, or `null` if never used. */
+    lastUsedAt: Date | null;
+    /** When this API key was created. */
+    createdAt: Date;
+    /** When this API key was last updated. */
+    updatedAt: Date | undefined;
+    /** @internal */
+    constructor(data: ApiKeyData);
+}
+/** Payload for creating an API key. */
+export interface CreateApiKeyPayload {
+    /** Display name for the key. */
+    name: string;
+    /** Optional description visible in the panel. */
+    description?: string;
+    /** Permissions granted to the key. */
+    permissions: string[];
+}
+/** Result returned when creating a new API key. */
+export interface CreateApiKeyResult {
+    /** The newly issued bearer token. Returned only once. */
+    token: string;
+    /**
+     * Best-effort lookup of the created key metadata from the API.
+     *
+     * This can be `null` because the create endpoint currently returns only the token,
+     * not the full resource representation.
+     */
+    apiKey: ApiKey | null;
+}
+/** Typed events emitted by {@link ApiKeysNamespace}. */
+export interface ApiKeyEvents {
+    /** Fired after a new API key is created. Payload includes the one-time token. */
+    created: CreateApiKeyResult;
+}
+/**
+ * Namespace for API key management.
+ *
+ * Access via `api.apiKeys`.
+ *
+ * @example
+ * ```ts ignore
+ * // List existing API keys
+ * const keys = await api.apiKeys.list();
+ *
+ * // Create a new API key
+ * const created = await api.apiKeys.create({
+ *   name: 'My Integration',
+ *   permissions: ['server.read'],
+ * });
+ * console.log(created.token); // Save this - it won't be shown again!
+ * ```
+ */
+export declare class ApiKeysNamespace extends ResourceNamespace<ApiKey, ApiKeyEvents> {
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Fetch a paginated list of API keys for the current account.
+     *
+     * Note: the `token` field is not included in list responses.
+     *
+     * @param opts Pagination options.
+     */
+    list(opts?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<Paginated<ApiKey>>;
+    /**
+     * Create a new API key.
+     *
+     * The returned {@link ApiKey} contains the `token` field with the full bearer token value.
+     * This is the **only** time the token is returned by the API - store it securely.
+     *
+     * @param name A descriptive name for the key, e.g. `"CI/CD Pipeline"`.
+     */
+    create(payload: CreateApiKeyPayload): Promise<CreateApiKeyResult>;
+}
+export {};
+//# sourceMappingURL=api-keys.d.ts.map

package/script/src/resources/api-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.d.ts","sourceRoot":"","sources":["../../../src/src/resources/api-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,SAAS,EAAY,MAAM,aAAa,CAAC;AAElF,8CAA8C;AAC9C,UAAU,UAAU;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAQD;;;;;;;GAOG;AACH,qBAAa,MAAO,SAAQ,gBAAgB;IAC3C,mCAAmC;IACnC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,qCAAqC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACpB,6CAA6C;IACtC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C;;;;;OAKG;IACI,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,sFAAsF;IAC/E,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IAC/B,qCAAqC;IAC9B,SAAS,EAAE,IAAI,CAAC;IACvB,0CAA0C;IACnC,SAAS,EAAE,IAAI,GAAG,SAAS,CAAC;IAEnC,gBAAgB;gBACG,IAAI,EAAE,UAAU;CAUnC;AAED,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IACnC,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IAClC,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC5B,iFAAiF;IACjF,OAAO,EAAE,kBAAkB,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,gBAAiB,SAAQ,iBAAiB,CAAC,MAAM,EAAE,YAAY,CAAC;IAC5E,gBAAgB;gBACG,IAAI,EAAE,UAAU;IAInC;;;;;;OAMG;IACU,IAAI,CAChB,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAC5C,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAO7B;;;;;;;OAOG;IACU,MAAM,CAClB,OAAO,EAAE,mBAAmB,GAC1B,OAAO,CAAC,kBAAkB,CAAC;CAuB9B"}

package/script/src/resources/api-keys.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiKeysNamespace = exports.ApiKey = void 0;
+const namespace_js_1 = require("../namespace.js");
+const reactive_js_1 = require("../reactive.js");
+const types_js_1 = require("../types.js");
+/**
+ * An API key credential for authenticating programmatic access to the MeowPanel API.
+ *
+ * Retrieved via {@link ApiKeysNamespace.list} or {@link ApiKeysNamespace.create}.
+ *
+ * > **Note:** The `token` field is only populated when the key is first created.
+ * > It cannot be retrieved again after that. Store it securely.
+ */
+class ApiKey extends reactive_js_1.ReactiveResource {
+    /** The API key's unique NanoID. */
+    id;
+    /** Display name for this API key. */
+    name;
+    /** Optional description for this API key. */
+    description;
+    /**
+     * The bearer token value.
+     *
+     * Only populated immediately after creation via {@link ApiKeysNamespace.create}.
+     * `undefined` on all subsequent fetches - store it securely when first received.
+     */
+    token;
+    /** When this key was last used to authenticate a request, or `null` if never used. */
+    lastUsedAt;
+    /** When this API key was created. */
+    createdAt;
+    /** When this API key was last updated. */
+    updatedAt;
+    /** @internal */
+    constructor(data) {
+        super();
+        this.id = (0, types_js_1.toNanoID)(data.id);
+        this.name = data.name;
+        this.description = data.description;
+        this.token = data.token;
+        this.lastUsedAt = data.last_used_at ? new Date(data.last_used_at) : null;
+        this.createdAt = new Date(data.created_at);
+        this.updatedAt = data.updated_at ? new Date(data.updated_at) : undefined;
+    }
+}
+exports.ApiKey = ApiKey;
+/**
+ * Namespace for API key management.
+ *
+ * Access via `api.apiKeys`.
+ *
+ * @example
+ * ```ts ignore
+ * // List existing API keys
+ * const keys = await api.apiKeys.list();
+ *
+ * // Create a new API key
+ * const created = await api.apiKeys.create({
+ *   name: 'My Integration',
+ *   permissions: ['server.read'],
+ * });
+ * console.log(created.token); // Save this - it won't be shown again!
+ * ```
+ */
+class ApiKeysNamespace extends namespace_js_1.ResourceNamespace {
+    /** @internal */
+    constructor(http) {
+        super(http);
+    }
+    /**
+     * Fetch a paginated list of API keys for the current account.
+     *
+     * Note: the `token` field is not included in list responses.
+     *
+     * @param opts Pagination options.
+     */
+    async list(opts = {}) {
+        const result = await this.http.list('/api-keys', opts);
+        const keys = result.data.map((d) => new ApiKey(d));
+        this.setCache(keys);
+        return { ...result, data: keys };
+    }
+    /**
+     * Create a new API key.
+     *
+     * The returned {@link ApiKey} contains the `token` field with the full bearer token value.
+     * This is the **only** time the token is returned by the API - store it securely.
+     *
+     * @param name A descriptive name for the key, e.g. `"CI/CD Pipeline"`.
+     */
+    async create(payload) {
+        const data = await this.http.post('/api-keys', payload);
+        // The create endpoint returns only the one-time token, not the full resource.
+        // We re-list and match by name to hydrate the ApiKey instance. This is best-effort:
+        // if matching is ambiguous (multiple keys with the same name), `apiKey` may be wrong.
+        const listed = await this.list({ perPage: 100 });
+        const apiKey = [...listed.data]
+            .filter((key) => key.name === payload.name)
+            .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())[0] ??
+            null;
+        const created = {
+            token: data.key,
+            apiKey,
+        };
+        this.emit('created', created);
+        return created;
+    }
+}
+exports.ApiKeysNamespace = ApiKeysNamespace;

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

@@ -0,0 +1,57 @@
+import type { HttpClient } from '../http.js';
+/**
+ * A single authentication provider and its display configuration.
+ */
+export interface AuthProvider {
+    /** Provider-specific display fields, e.g. `{ display_name: 'WHMCS' }`. */
+    fields: Record<string, string>;
+}
+/**
+ * Metadata about the panel's authentication configuration.
+ */
+export interface AuthMeta {
+    /** Available auth providers keyed by provider ID (e.g. `'email'`, `'whmcs'`). */
+    providers: Record<string, AuthProvider>;
+}
+/** Response from the token refresh endpoint. */
+export interface RefreshResponse {
+    access_token: string;
+    expires_in_seconds: number;
+    token_type: string;
+    account?: Record<string, unknown>;
+}
+/** Options for the refresh request. */
+export interface RefreshOptions {
+    /** Fields to include in the response (e.g. `['account', 'display']`). */
+    include?: string[];
+}
+/**
+ * Resource for authentication configuration.
+ *
+ * Access via `api.auth`.
+ *
+ * @example
+ * ```ts ignore
+ * const { providers } = await api.auth.getMeta();
+ * if (providers.email) console.log('Email login available');
+ * if (providers.whmcs) console.log('WHMCS:', providers.whmcs.fields.display_name);
+ * ```
+ */
+export declare class AuthResource {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Fetch the panel's authentication configuration.
+     *
+     * Returns the available login providers and their display fields.
+     */
+    getMeta(): Promise<AuthMeta>;
+    /**
+     * Exchange a refresh token for a short-lived JWT access token.
+     *
+     * Used for exhanging tokens via cookies, managed by the host.
+     */
+    refresh(opts?: RefreshOptions): Promise<RefreshResponse>;
+}
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/src/resources/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAS7C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACxC;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC9B,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IAEL,OAAO,CAAC,QAAQ,CAAC,IAAI;IADxC,gBAAgB;gBACoB,IAAI,EAAE,UAAU;IAEpD;;;;OAIG;IACI,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC;IAInC;;;;OAIG;IACI,OAAO,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;CAQnE"}

package/script/src/resources/auth.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthResource = void 0;
+/**
+ * Resource for authentication configuration.
+ *
+ * Access via `api.auth`.
+ *
+ * @example
+ * ```ts ignore
+ * const { providers } = await api.auth.getMeta();
+ * if (providers.email) console.log('Email login available');
+ * if (providers.whmcs) console.log('WHMCS:', providers.whmcs.fields.display_name);
+ * ```
+ */
+class AuthResource {
+    http;
+    /** @internal */
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Fetch the panel's authentication configuration.
+     *
+     * Returns the available login providers and their display fields.
+     */
+    getMeta() {
+        return this.http.get('/auth');
+    }
+    /**
+     * Exchange a refresh token for a short-lived JWT access token.
+     *
+     * Used for exhanging tokens via cookies, managed by the host.
+     */
+    refresh(opts = {}) {
+        const params = {};
+        if (opts.include?.length) {
+            params['include'] = opts.include.join(',');
+        }
+        return this.http.post('/auth/refresh', undefined, { params });
+    }
+}
+exports.AuthResource = AuthResource;