@noctaly/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,784 @@
+/**
+ * Internal config object threaded through every resource. Not part of the public API.
+ */
+interface ClientConfig {
+    apiKey: string;
+    baseURL: string;
+    /**
+     * Maximum number of automatic retries before throwing. @default 3
+     */
+    maxRetries: number;
+    /**
+     * Whether to automatically retry on `rate_limited` (429) responses. @default true
+     */
+    retry: boolean;
+    /**
+     * Request timeout in milliseconds. `0` disables the timeout. @default 30_000
+     */
+    timeout: number;
+}
+
+/**
+ * An item defined in a guild's economy shop.
+ */
+interface Item {
+    /**
+     * Buy price in the shop.
+     */
+    buyPrice: number;
+    /**
+     * Cooldown between uses, in seconds (`0` = no cooldown).
+     */
+    cooldown: number;
+    /**
+     * Optional description.
+     */
+    description: string | null;
+    /**
+     * Full durability per item (`0` = no durability), or `null`.
+     */
+    durability: number | null;
+    /**
+     * Emoji string, or `null`.
+     */
+    emoji: string | null;
+    /**
+     * `"UNICODE"`, `"CUSTOM"`, or `null`.
+     */
+    emojiType: "CUSTOM" | "UNICODE" | null;
+    /**
+     * Item flags (e.g. `["KEEP_AFTER_USE"]`).
+     */
+    flags: string[];
+    /**
+     * URL to a custom icon, or `null`.
+     */
+    iconURL: string | null;
+    /**
+     * UUID of the item.
+     */
+    id: string;
+    /**
+     * Display name.
+     */
+    name: string;
+    /**
+     * Current quantity in the shop, or `null` for unlimited.
+     */
+    quantity: number | null;
+    /**
+     * Per-member quantity limit, or `null` for unlimited.
+     */
+    quantityLimit: number | null;
+    /**
+     * Sell price.
+     */
+    sellPrice: number;
+    /**
+     * Item type (e.g. `"CUSTOM"`).
+     */
+    type: string;
+}
+/**
+ * A chest defined in a guild's economy shop.
+ */
+interface Chest {
+    /**
+     * Buy price.
+     */
+    buyPrice: number;
+    /**
+     * Chest flags (e.g. `["ANIMATED"]`).
+     */
+    flags: string[];
+    /**
+     * URL to a custom icon, or `null`.
+     */
+    iconURL: string | null;
+    /**
+     * UUID of the chest.
+     */
+    id: string;
+    /**
+     * Number of items drawn when opened.
+     */
+    itemDrawCount: number;
+    /**
+     * Display name.
+     */
+    name: string;
+    /**
+     * Primary hex colour (without `#`).
+     */
+    primaryColor: string;
+    /**
+     * Current quantity in the shop, or `null` for unlimited.
+     */
+    quantity: number | null;
+    /**
+     * Per-member quantity limit, or `null` for unlimited.
+     */
+    quantityLimit: number | null;
+    /**
+     * Secondary hex colour (without `#`).
+     */
+    secondaryColor: string;
+    /**
+     * Sell price.
+     */
+    sellPrice: number;
+}
+/**
+ * An item entry in a member's inventory.
+ */
+interface UserItem {
+    /**
+     * Buy price.
+     */
+    buyPrice: number;
+    /**
+     * Optional description.
+     */
+    description: string | null;
+    /**
+     * Current durability of the active stack, or `null`.
+     */
+    durability: number | null;
+    /**
+     * Emoji string, or `null`.
+     */
+    emoji: string | null;
+    /**
+     * `"UNICODE"`, `"CUSTOM"`, or `null`.
+     */
+    emojiType: "CUSTOM" | "UNICODE" | null;
+    /**
+     * Item flags.
+     */
+    flags: string[];
+    /**
+     * URL to a custom icon, or `null`.
+     */
+    iconURL: string | null;
+    /**
+     * UUID of the item.
+     */
+    id: string;
+    /**
+     * Full durability per item (`0` = no durability).
+     */
+    maxDurability: number;
+    /**
+     * Display name.
+     */
+    name: string;
+    /**
+     * How many the member owns, or `null`.
+     */
+    quantity: number | null;
+    /**
+     * Sell price.
+     */
+    sellPrice: number;
+    /**
+     * Item type.
+     */
+    type: string;
+}
+/**
+ * A chest entry in a member's inventory.
+ */
+interface UserChest {
+    /**
+     * Buy price.
+     */
+    buyPrice: number;
+    /**
+     * Chest flags.
+     */
+    flags: string[];
+    /**
+     * URL to a custom icon, or `null`.
+     */
+    iconURL: string | null;
+    /**
+     * UUID of the chest.
+     */
+    id: string;
+    /**
+     * Display name.
+     */
+    name: string;
+    /**
+     * Primary hex colour (without `#`).
+     */
+    primaryColor: string;
+    /**
+     * How many the member owns.
+     */
+    quantity: number;
+    /**
+     * Secondary hex colour (without `#`).
+     */
+    secondaryColor: string;
+    /**
+     * Sell price.
+     */
+    sellPrice: number;
+}
+/**
+ * A member's daily-streak info.
+ */
+interface DailyStreak {
+    /**
+     * ISO 8601 timestamp of the last claim.
+     */
+    lastClaim: string;
+    /**
+     * Current consecutive streak count.
+     */
+    streak: number;
+}
+/**
+ * Query parameters for {@link UserResource.getEcoProfile}.
+ */
+interface EcoProfileOptions {
+    /**
+     * Include the member's chest inventory.
+     */
+    chests?: boolean;
+    /**
+     * Include the member's daily streak.
+     */
+    dailyStreak?: boolean;
+    /**
+     * Include the member's item inventory.
+     */
+    items?: boolean;
+}
+/**
+ * Conditional response type for {@link UserResource.getEcoProfile}.
+ * Optional relations are only present when their query param is `true`.
+ */
+type EcoProfileResult<O extends EcoProfileOptions> = (O extends {
+    chests: true;
+} ? {
+    chests: UserChest[];
+} : Record<never, never>) & (O extends {
+    dailyStreak: true;
+} ? {
+    dailyStreak: DailyStreak | null;
+} : Record<never, never>) & (O extends {
+    items: true;
+} ? {
+    items: UserItem[];
+} : Record<never, never>) & {
+    money: number;
+};
+/**
+ * Full levelling profile for a guild member.
+ */
+interface LevelProfile {
+    /**
+     * Current level.
+     */
+    level: number;
+    /**
+     * Total messages sent.
+     */
+    messages: number;
+    /**
+     * Remaining XP needed to reach the next level.
+     */
+    neededXp: number;
+    /**
+     * Total reactions added.
+     */
+    reactions: number;
+    /**
+     * Total XP across all levels.
+     */
+    totalXp: number;
+    /**
+     * Total minutes spent in voice channels.
+     */
+    voiceMinutes: number;
+    /**
+     * XP accumulated in the current level.
+     */
+    xp: number;
+}
+/**
+ * Result returned after triggering an item's actions.
+ */
+interface UseItemResult {
+    /**
+     * Map of chest UUID → quantity added.
+     */
+    addedChests: Record<string, number>;
+    /**
+     * Map of item UUID → quantity added.
+     */
+    addedItems: Record<string, number>;
+    /**
+     * Role IDs added to the member.
+     */
+    addedRoles: string[];
+    /**
+     * Map of chest UUID → quantity removed.
+     */
+    chestsRemoved: Record<string, number>;
+    /**
+     * Map of item UUID → quantity removed.
+     */
+    itemsRemoved: Record<string, number>;
+    /**
+     * Total money awarded (negative if removed).
+     */
+    money: number;
+    /**
+     * Role IDs removed from the member.
+     */
+    removedRoles: string[];
+    /**
+     * Map of role ID → Unix timestamp when the temporary role expires.
+     */
+    rolesDuration: Record<string, number>;
+    /**
+     * Total XP awarded (negative if removed).
+     */
+    xp: number;
+}
+/**
+ * Rate-limit information parsed from response headers.
+ */
+interface RateLimitInfo {
+    /**
+     * Maximum requests allowed in the window.
+     */
+    limit: number;
+    /**
+     * Requests remaining in the current window.
+     */
+    remaining: number;
+    /**
+     * Unix timestamp (seconds) when the window resets.
+     */
+    reset: number;
+    /**
+     * Seconds until the window resets.
+     */
+    resetAfter: number;
+}
+
+interface NoctalyResponse<T> {
+    /**
+     * The parsed response data.
+     */
+    data: T;
+    /**
+     * Rate-limit info from the response headers.
+     * Present on all successful responses that include rate-limit headers.
+     */
+    rateLimit?: RateLimitInfo;
+}
+
+/**
+ * Manages guild-level chest operations.
+ */
+declare class GuildChestsResource {
+    #private;
+    constructor(guildID: string, config: ClientConfig);
+    /**
+     * Returns all chests configured in the guild's economy.
+     *
+     * `GET /guilds/{guildID}/chests`
+     */
+    list(): Promise<NoctalyResponse<{
+        chests: Chest[];
+    }>>;
+}
+
+/**
+ * Manages guild-level item operations.
+ */
+declare class GuildItemsResource {
+    #private;
+    constructor(guildID: string, config: ClientConfig);
+    /**
+     * Returns all items configured in the guild's economy.
+     *
+     * `GET /guilds/{guildID}/items`
+     */
+    list(): Promise<NoctalyResponse<{
+        items: Item[];
+    }>>;
+}
+
+interface AddChestsBody {
+    /**
+     * UUID of the chest to add.
+     */
+    chestID: string;
+    /**
+     * Quantity to add. Min: `1`. Max: `1,000,000`.
+     */
+    quantity: number;
+}
+interface RemoveChestsBody {
+    /**
+     * UUID of the chest to remove.
+     */
+    chestID: string;
+    /**
+     * Quantity to remove. Min: `1`. Max: `1,000,000`.
+     */
+    quantity: number;
+}
+interface SetChestQuantityBody {
+    /**
+     * UUID of the chest.
+     */
+    chestID: string;
+    /**
+     * Target quantity. Min: `0` (removes the chest entirely). Max: `1,000,000`.
+     */
+    quantity: number;
+}
+/**
+ * Manages chest operations for a specific guild member.
+ */
+declare class UserChestsResource {
+    #private;
+    constructor(guildID: string, userID: string, config: ClientConfig);
+    /**
+     * Adds a quantity of a chest to the member's inventory.
+     *
+     * `POST /guilds/{guildID}/users/{userID}/chests`
+     */
+    add(body: AddChestsBody): Promise<NoctalyResponse<{
+        quantity: number;
+    }>>;
+    /**
+     * Removes a quantity of a chest from the member's inventory. If the
+     * resulting quantity reaches `0` or below the chest is removed entirely.
+     *
+     * `DELETE /guilds/{guildID}/users/{userID}/chests`
+     */
+    remove(body: RemoveChestsBody): Promise<NoctalyResponse<{
+        quantity: number;
+    }>>;
+    /**
+     * Sets the exact quantity of a chest in the member's inventory.
+     * Passing `0` removes the chest entirely.
+     *
+     * `PUT /guilds/{guildID}/users/{userID}/chests`
+     */
+    set(body: SetChestQuantityBody): Promise<NoctalyResponse<{
+        quantity: number;
+    }>>;
+}
+
+interface AddItemsBody {
+    /**
+     * UUID of the item to add.
+     */
+    itemID: string;
+    /**
+     * Quantity to add. Min: `1`. Max: `1,000,000`.
+     */
+    quantity: number;
+}
+interface RemoveItemsBody {
+    /**
+     * UUID of the item to remove.
+     */
+    itemID: string;
+    /**
+     * Quantity to remove. Min: `1`. Max: `1,000,000`.
+     */
+    quantity: number;
+}
+interface SetItemQuantityBody {
+    /**
+     * UUID of the item.
+     */
+    itemID: string;
+    /**
+     * Target quantity. Min: `0` (removes the item entirely). Max: `1,000,000`.
+     */
+    quantity: number;
+}
+interface UseItemBody {
+    /**
+     * Number of uses. Min: `1`. Max: `1,000,000`. Defaults to `1`.
+     */
+    quantity?: number;
+}
+/**
+ * Manages item operations for a specific guild member.
+ */
+declare class UserItemsResource {
+    #private;
+    constructor(guildID: string, userID: string, config: ClientConfig);
+    /**
+     * Adds a quantity of an item to the member's inventory.
+     *
+     * `POST /guilds/{guildID}/users/{userID}/items`
+     */
+    add(body: AddItemsBody): Promise<NoctalyResponse<{
+        quantity: number;
+    }>>;
+    /**
+     * Removes a quantity of an item from the member's inventory. If the
+     * resulting quantity reaches `0` or below the item is removed entirely.
+     *
+     * `DELETE /guilds/{guildID}/users/{userID}/items`
+     */
+    remove(body: RemoveItemsBody): Promise<NoctalyResponse<{
+        quantity: number;
+    }>>;
+    /**
+     * Sets the exact quantity of an item in the member's inventory.
+     * Passing `0` removes the item entirely.
+     *
+     * `PUT /guilds/{guildID}/users/{userID}/items`
+     */
+    set(body: SetItemQuantityBody): Promise<NoctalyResponse<{
+        quantity: number;
+    }>>;
+    /**
+     * Triggers the item's configured actions (give/remove money, XP, roles,
+     * other items…). Only works for items of type `CUSTOM` with at least one
+     * action. The item is consumed unless it has the `KEEP_AFTER_USE` flag.
+     *
+     * `POST /guilds/{guildID}/users/{userID}/items/{itemID}/use`
+     */
+    use(itemID: string, body?: UseItemBody): Promise<NoctalyResponse<UseItemResult>>;
+}
+
+interface UpdateXPBody {
+    /**
+     * When `true`, the server multiplier and the member's booster roles
+     * affect the amount of XP.
+     *
+     * @default false
+     */
+    multiply?: boolean;
+    /**
+     * XP to give (positive) or remove (negative).
+     * Min: `-100,000,000`. Max: `100,000,000`.
+     */
+    xp: number;
+}
+interface UpdateLevelBody {
+    /**
+     * Levels to give (positive) or remove (negative).
+     * Min: `-1,000`. Max: `1,000`.
+     */
+    level: number;
+}
+interface UpdateMoneyBody {
+    /**
+     * Money to give (positive) or remove (negative).
+     * Min: `-1,000,000,000`. Max: `1,000,000,000`.
+     */
+    money: number;
+    /**
+     * When `true`, the server multiplier and the member's booster roles
+     * affect the amount of money.
+     *
+     * @default false
+     */
+    multiply?: boolean;
+}
+/**
+ * Operations scoped to a single guild member.
+ */
+declare class UserResource {
+    #private;
+    /**
+     * Item inventory operations for this member.
+     */
+    readonly items: UserItemsResource;
+    /**
+     * Chest inventory operations for this member.
+     */
+    readonly chests: UserChestsResource;
+    constructor(guildID: string, userID: string, config: ClientConfig);
+    /**
+     * Returns the member's economy profile.
+     * Pass options to include optional relations (items, chests, daily streak).
+     *
+     * `GET /guilds/{guildID}/users/{userID}/eco-profile`
+     */
+    getEcoProfile(): Promise<NoctalyResponse<EcoProfileResult<Record<never, never>>>>;
+    getEcoProfile<O extends EcoProfileOptions>(options: O): Promise<NoctalyResponse<EcoProfileResult<O>>>;
+    /**
+     * Returns the member's full levelling profile.
+     *
+     * `GET /guilds/{guildID}/users/{userID}/level-profile`
+     */
+    getLevelProfile(): Promise<NoctalyResponse<LevelProfile>>;
+    /**
+     * Adds or removes XP from the member.
+     *
+     * `POST /guilds/{guildID}/users/{userID}/xp`
+     */
+    updateXP(body: UpdateXPBody): Promise<NoctalyResponse<{
+        xp: number;
+    }>>;
+    /**
+     * Adds or removes levels from the member.
+     *
+     * `POST /guilds/{guildID}/users/{userID}/level`
+     */
+    updateLevel(body: UpdateLevelBody): Promise<NoctalyResponse<{
+        level: number;
+    }>>;
+    /**
+     * Adds or removes money from the member.
+     *
+     * `POST /guilds/{guildID}/users/{userID}/money`
+     */
+    updateMoney(body: UpdateMoneyBody): Promise<NoctalyResponse<{
+        money: number;
+    }>>;
+}
+
+/**
+ * Operations scoped to a single guild.
+ */
+declare class GuildResource {
+    #private;
+    /**
+     * Guild-wide item catalogue operations.
+     */
+    readonly items: GuildItemsResource;
+    /**
+     * Guild-wide chest catalogue operations.
+     */
+    readonly chests: GuildChestsResource;
+    constructor(guildID: string, config: ClientConfig);
+    /**
+     * Returns a {@link UserResource} scoped to the given guild member.
+     *
+     * @param userID - Discord user ID of the member.
+     */
+    users(userID: string): UserResource;
+}
+
+interface NoctalyClientOptions {
+    /**
+     * Your Noctaly API key.
+     */
+    apiKey: string;
+    /**
+     * Override the base URL. Useful for self-hosted or staging environments.
+     *
+     * @default "https://noctaly.com/api/v1"
+     */
+    baseURL?: string;
+    /**
+     * Maximum number of automatic retries before the error is thrown.
+     *
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Automatically retry requests that receive a `rate_limited` (429) response,
+     * waiting `retryAfter` seconds between attempts.
+     *
+     * @default true
+     */
+    retry?: boolean;
+    /**
+     * Request timeout in milliseconds. Set to `0` to disable.
+     *
+     * @default 30_000
+     */
+    timeout?: number;
+}
+/**
+ * Entry point for the Noctaly SDK.
+ *
+ * @example
+ * ```ts
+ * import { NoctalyClient } from "@noctaly/sdk";
+ *
+ * const noctaly = new NoctalyClient({ apiKey: "your-api-key" });
+ *
+ * const { data } = await noctaly.guilds("GUILD_ID").users("USER_ID").getLevelProfile();
+ * console.log(`Level ${data.level} — ${data.xp} XP`);
+ * ```
+ */
+declare class NoctalyClient {
+    #private;
+    constructor({ apiKey, baseURL, timeout, retry, maxRetries, }: NoctalyClientOptions);
+    /**
+     * Returns a {@link GuildResource} scoped to the given guild.
+     *
+     * @param guildID - Discord guild (server) ID.
+     */
+    guilds(guildID: string): GuildResource;
+}
+
+/**
+ * All possible error codes returned by the Noctaly API.
+ */
+type ApiErrorCode = "module_disabled" | "not_found" | "rate_limited" | "unauthenticated" | "unauthorized" | "unexpected_error" | "validation_error";
+/**
+ * A single Zod validation issue surfaced by the API.
+ */
+interface ValidationIssue {
+    /**
+     * Zod error code.
+     */
+    code: string;
+    /**
+     * Human-readable error message.
+     */
+    message: string;
+    /**
+     * Path to the field that failed validation.
+     */
+    path: (number | string)[];
+}
+/**
+ * Thrown by all SDK methods on a non-2xx API response.
+ */
+declare class NoctalyError extends Error {
+    /**
+     * Machine-readable error code.
+     */
+    readonly code: ApiErrorCode;
+    /**
+     * HTTP status code.
+     */
+    readonly status: number;
+    /**
+     * Seconds to wait before retrying. Only present when `code` is
+     * `"rate_limited"`.
+     */
+    readonly retryAfter?: number;
+    /**
+     * `true` when the rate limit that was exceeded is the global one.
+     * Only present when `code` is `"rate_limited"`.
+     */
+    readonly global?: boolean;
+    /**
+     * Zod validation issues. Only present when `code` is
+     * `"validation_error"`.
+     */
+    readonly details?: ValidationIssue[];
+    constructor(opts: {
+        code: ApiErrorCode;
+        details?: ValidationIssue[];
+        global?: boolean;
+        message: string;
+        retryAfter?: number;
+        status: number;
+    });
+}
+
+export { type AddChestsBody, type AddItemsBody, type ApiErrorCode, type Chest, type DailyStreak, type EcoProfileOptions, type EcoProfileResult, GuildChestsResource, GuildItemsResource, GuildResource, type Item, type LevelProfile, NoctalyClient, type NoctalyClientOptions, NoctalyError, type NoctalyResponse, type RateLimitInfo, type RemoveChestsBody, type RemoveItemsBody, type SetChestQuantityBody, type SetItemQuantityBody, type UpdateLevelBody, type UpdateMoneyBody, type UpdateXPBody, type UseItemBody, type UseItemResult, type UserChest, UserChestsResource, type UserItem, UserItemsResource, UserResource, type ValidationIssue };