@erinjs/core 1.0.0

package/core/packages/types/src/rest/routes.ts

@@ -0,0 +1,109 @@
+import { Snowflake } from '../common/snowflake.js';
+
+/**
+ * Route builder helpers for REST API.
+ * All routes are relative to /v1
+ */
+export const Routes = {
+  // Channels
+  channel: (id: Snowflake) => `/channels/${id}` as const,
+  channelMessages: (id: Snowflake) => `/channels/${id}/messages` as const,
+  channelMessage: (channelId: Snowflake, messageId: Snowflake) =>
+    `/channels/${channelId}/messages/${messageId}` as const,
+  channelMessageReactions: (channelId: Snowflake, messageId: Snowflake) =>
+    `/channels/${channelId}/messages/${messageId}/reactions` as const,
+  channelMessageReaction: (channelId: Snowflake, messageId: Snowflake, emoji: string) =>
+    `/channels/${channelId}/messages/${messageId}/reactions/${encodeURIComponent(emoji)}` as const,
+  channelPins: (id: Snowflake) => `/channels/${id}/messages/pins` as const,
+  /** Use channelPinMessage for PUT/DELETE pin operations. */
+  channelPin: (channelId: Snowflake, messageId: Snowflake) =>
+    `/channels/${channelId}/messages/pins/${messageId}` as const,
+  /** Pin/unpin: PUT or DELETE /channels/{id}/pins/{messageId}. Use for pin and unpin operations. */
+  channelPinMessage: (channelId: Snowflake, messageId: Snowflake) =>
+    `/channels/${channelId}/pins/${messageId}` as const,
+  channelBulkDelete: (id: Snowflake) => `/channels/${id}/messages/bulk-delete` as const,
+  channelWebhooks: (id: Snowflake) => `/channels/${id}/webhooks` as const,
+  channelTyping: (id: Snowflake) => `/channels/${id}/typing` as const,
+  channelInvites: (id: Snowflake) => `/channels/${id}/invites` as const,
+  channelPermission: (channelId: Snowflake, overwriteId: Snowflake) =>
+    `/channels/${channelId}/permissions/${overwriteId}` as const,
+  channelRecipient: (channelId: Snowflake, userId: Snowflake) =>
+    `/channels/${channelId}/recipients/${userId}` as const,
+  channelMessageAttachment: (channelId: Snowflake, messageId: Snowflake, attachmentId: Snowflake) =>
+    `/channels/${channelId}/messages/${messageId}/attachments/${attachmentId}` as const,
+
+  // Guilds
+  guilds: () => '/guilds' as const,
+  guild: (id: Snowflake) => `/guilds/${id}` as const,
+  guildDelete: (guildId: Snowflake) => `/guilds/${guildId}/delete` as const,
+  guildVanityUrl: (guildId: Snowflake) => `/guilds/${guildId}/vanity-url` as const,
+  guildTextChannelFlexibleNames: (guildId: Snowflake) =>
+    `/guilds/${guildId}/text-channel-flexible-names` as const,
+  guildDetachedBanner: (guildId: Snowflake) => `/guilds/${guildId}/detached-banner` as const,
+  guildDisallowUnclaimedAccounts: (guildId: Snowflake) =>
+    `/guilds/${guildId}/disallow-unclaimed-accounts` as const,
+  guildTransferOwnership: (guildId: Snowflake) => `/guilds/${guildId}/transfer-ownership` as const,
+  guildRolesHoistPositions: (guildId: Snowflake) =>
+    `/guilds/${guildId}/roles/hoist-positions` as const,
+  guildEmojisBulk: (guildId: Snowflake) => `/guilds/${guildId}/emojis/bulk` as const,
+  guildStickersBulk: (guildId: Snowflake) => `/guilds/${guildId}/stickers/bulk` as const,
+  guildChannels: (id: Snowflake) => `/guilds/${id}/channels` as const,
+  guildMembers: (id: Snowflake) => `/guilds/${id}/members` as const,
+  guildMember: (guildId: Snowflake, userId: Snowflake) =>
+    `/guilds/${guildId}/members/${userId}` as const,
+  guildMemberRole: (guildId: Snowflake, userId: Snowflake, roleId: Snowflake) =>
+    `/guilds/${guildId}/members/${userId}/roles/${roleId}` as const,
+  guildRoles: (id: Snowflake) => `/guilds/${id}/roles` as const,
+  guildRole: (guildId: Snowflake, roleId: Snowflake) =>
+    `/guilds/${guildId}/roles/${roleId}` as const,
+  guildBans: (id: Snowflake) => `/guilds/${id}/bans` as const,
+  guildBan: (guildId: Snowflake, userId: Snowflake) => `/guilds/${guildId}/bans/${userId}` as const,
+  guildInvites: (id: Snowflake) => `/guilds/${id}/invites` as const,
+  invite: (code: string) => `/invites/${encodeURIComponent(code)}` as const,
+  guildAuditLogs: (id: Snowflake) => `/guilds/${id}/audit-logs` as const,
+  guildEmojis: (id: Snowflake) => `/guilds/${id}/emojis` as const,
+  guildEmoji: (guildId: Snowflake, emojiId: Snowflake) =>
+    `/guilds/${guildId}/emojis/${emojiId}` as const,
+  guildStickers: (id: Snowflake) => `/guilds/${id}/stickers` as const,
+  guildSticker: (guildId: Snowflake, stickerId: Snowflake) =>
+    `/guilds/${guildId}/stickers/${stickerId}` as const,
+  guildWebhooks: (id: Snowflake) => `/guilds/${id}/webhooks` as const,
+  webhook: (id: Snowflake) => `/webhooks/${id}` as const,
+  webhookExecute: (id: Snowflake, token: string) => `/webhooks/${id}/${token}` as const,
+  webhookMessage: (id: Snowflake, token: string, messageId: Snowflake) =>
+    `/webhooks/${id}/${token}/messages/${messageId}` as const,
+
+  // Users
+  user: (id: Snowflake) => `/users/${id}` as const,
+  currentUser: () => `/users/@me` as const,
+  currentUserGuilds: () => `/users/@me/guilds` as const,
+  leaveGuild: (guildId: Snowflake) => `/users/@me/guilds/${guildId}` as const,
+  userMeChannels: () => `/users/@me/channels` as const,
+  /** GET /users/{id}/profile. Pass guildId for server-specific profile. */
+  userProfile: (id: Snowflake, guildId?: Snowflake): string =>
+    guildId ? `/users/${id}/profile?guild_id=${guildId}` : `/users/${id}/profile`,
+
+  // Instance (unauthenticated)
+  instanceDiscovery: () => '/.well-known/fluxer' as const,
+  instance: () => '/instance' as const,
+
+  // Gateway
+  gatewayBot: () => `/gateway/bot` as const,
+
+  // Streams (voice channel screen share preview)
+  streamPreview: (streamKey: string) =>
+    `/streams/${encodeURIComponent(streamKey)}/preview` as const,
+
+  // Application commands (slash commands)
+  applicationCommands: (applicationId: Snowflake) =>
+    `/applications/${applicationId}/commands` as const,
+  applicationCommand: (applicationId: Snowflake, commandId: Snowflake) =>
+    `/applications/${applicationId}/commands/${commandId}` as const,
+  interactionCallback: (interactionId: Snowflake, interactionToken: string) =>
+    `/interactions/${interactionId}/${interactionToken}/callback` as const,
+
+  // OAuth2 / Bot
+  oauth2ApplicationBot: (id: Snowflake) => `/oauth2/applications/${id}/bot` as const,
+  oauth2ApplicationBotResetToken: (id: Snowflake) =>
+    `/oauth2/applications/${id}/bot/reset-token` as const,
+} as const;

package/core/packages/types/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "noEmit": false
+  },
+  "include": ["src/**/*"]
+}

package/core/packages/types/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  splitting: false,
+  clean: true,
+});

package/core/packages/types/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+  },
+});

package/core/packages/util/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@erinjs/util",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.2.4",
+  "description": "Shared utilities for @erinjs/core",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blstmo-abandoned-us-for-the-milk/core.git",
+    "directory": "packages/util"
+  },
+  "bugs": "https://github.com/blstmo-abandoned-us-for-the-milk/core/issues",
+  "homepage": "https://github.com/blstmo-abandoned-us-for-the-milk/core#readme",
+  "keywords": [
+    "fluxer",
+    "util",
+    "snowflake",
+    "bitfield"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@erinjs/types": "workspace:*"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "pnpm exec tsx ../../scripts/generate-emoji-shortcodes.ts && tsup",
+    "clean": "rm -rf dist",
+    "lint": "eslint src --max-warnings 0 --config ../../eslint.config.js",
+    "lint:fix": "eslint src --fix --config ../../eslint.config.js",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.18"
+  }
+}

package/core/packages/util/src/BitField.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import { BitField } from './BitField.js';
+
+// Minimal BitField subclass for testing
+class TestBitField extends BitField<'A' | 'B' | 'C'> {
+  static override Flags = { A: 1n, B: 2n, C: 4n };
+}
+
+describe('BitField', () => {
+  it('creates with default bit 0', () => {
+    const bf = new TestBitField();
+    expect(bf.bitfield).toBe(0n);
+  });
+
+  it('resolves number', () => {
+    const bf = new TestBitField(3);
+    expect(bf.bitfield).toBe(3n);
+  });
+
+  it('resolves string flag', () => {
+    const bf = new TestBitField('A');
+    expect(bf.bitfield).toBe(1n);
+  });
+
+  it('resolves array of flags with OR', () => {
+    const bf = new TestBitField(['A', 'B']);
+    expect(bf.bitfield).toBe(3n); // 1 | 2
+  });
+
+  it('has checks single bit', () => {
+    const bf = new TestBitField(['A', 'B']);
+    expect(bf.has('A')).toBe(true);
+    expect(bf.has('B')).toBe(true);
+    expect(bf.has('C')).toBe(false);
+  });
+
+  it('has checks number', () => {
+    const bf = new TestBitField(3);
+    expect(bf.has(2)).toBe(true);
+  });
+
+  it('has requires all bits for composite checks', () => {
+    const bf = new TestBitField('A');
+    expect(bf.has(['A', 'B'])).toBe(false);
+    bf.add('B');
+    expect(bf.has(['A', 'B'])).toBe(true);
+  });
+
+  it('resolves numeric bigint string literal', () => {
+    const bf = new TestBitField('8');
+    expect(bf.bitfield).toBe(8n);
+  });
+
+  it('add sets bits', () => {
+    const bf = new TestBitField('A').add('B');
+    expect(bf.bitfield).toBe(3n);
+  });
+
+  it('remove unsets bits', () => {
+    const bf = new TestBitField(['A', 'B', 'C']).remove('B');
+    expect(bf.bitfield).toBe(5n); // A | C
+  });
+
+  it('serialize returns object', () => {
+    const bf = new TestBitField(['A', 'C']);
+    const s = bf.serialize();
+    expect(s).toEqual({ A: true, B: false, C: true });
+  });
+
+  it('toArray returns enabled flags', () => {
+    const bf = new TestBitField(['A', 'C']);
+    expect(bf.toArray()).toEqual(['A', 'C']);
+  });
+
+  it('toJSON returns serialized string', () => {
+    const bf = new TestBitField(5);
+    expect(bf.toJSON()).toBe('5');
+  });
+
+  it('equals compares bitfields', () => {
+    const a = new TestBitField(['A', 'B']);
+    const b = new TestBitField(3);
+    const c = new TestBitField('A');
+    expect(a.equals(b)).toBe(true);
+    expect(a.equals(c)).toBe(false);
+  });
+
+  it('freeze returns frozen instance', () => {
+    const bf = new TestBitField('A').freeze();
+    expect(Object.isFrozen(bf)).toBe(true);
+  });
+
+  it('throws for invalid flag string', () => {
+    expect(() => new TestBitField('Invalid' as 'A')).toThrow(RangeError);
+  });
+});

package/core/packages/util/src/BitField.ts

@@ -0,0 +1,105 @@
+/**
+ * Data structure that allows efficient storage of multiple flags (bits) in a single number.
+ *
+ * Note: JavaScript bitwise operations (|, &, ^, <<, >>) operate on 32-bit signed integers.
+ * Flags with values exceeding 2^30 may exhibit unexpected behavior. For permission-style
+ * bitfields with more than 30 bits, consider using BigInt-based implementations.
+ */
+export type BitFieldResolvable<S extends string> =
+  | S
+  | bigint
+  | number
+  | BitField<S>
+  | (S | number | bigint | BitField<S>)[];
+
+export class BitField<S extends string> {
+  static Flags: Record<string, bigint> = {};
+  defaultBit = 0;
+  bitfield: bigint;
+
+  constructor(bits: BitFieldResolvable<S> = 0) {
+    this.bitfield = (this.constructor as typeof BitField).resolve(bits);
+  }
+
+  get [Symbol.toStringTag](): string {
+    return `BitField${this.bitfield}`;
+  }
+
+  static resolve<S extends string>(bits: BitFieldResolvable<S>): bigint {
+    if (typeof bits === 'number' && bits >= 0) return BigInt(bits);
+    if (typeof bits === 'bigint' && bits >= 0n) return bits;
+    if (bits instanceof BitField) return bits.bitfield;
+    if (Array.isArray(bits))
+      return bits.map((b) => this.resolve(b)).reduce((a, b) => BigInt(a) | BigInt(b), 0n);
+    if (typeof bits === 'string') {
+      // If the string matches a known flag name, return its bigint value
+      if (bits in this.Flags) {
+        return this.Flags[bits as S];
+      }
+
+      // Otherwise, try to interpret the string as a valid non-negative bigint literal
+      try {
+        const value = BigInt(bits);
+        if (value >= 0n) return value;
+      } catch {
+        // fall through to error below
+      }
+    }
+    throw new RangeError(`Invalid bitfield flag or number: ${bits}`);
+  }
+
+  has(bit: BitFieldResolvable<S>): boolean {
+    bit = (this.constructor as typeof BitField).resolve(bit);
+    return (this.bitfield & bit) === bit;
+  }
+
+  add(...bits: BitFieldResolvable<S>[]): this {
+    let total = 0n;
+    for (const bit of bits) {
+      total |= (this.constructor as typeof BitField).resolve(bit);
+    }
+    this.bitfield |= total;
+    return this;
+  }
+
+  remove(...bits: BitFieldResolvable<S>[]): this {
+    let total = 0n;
+    for (const bit of bits) {
+      total |= (this.constructor as typeof BitField).resolve(bit);
+    }
+    this.bitfield &= ~total;
+    return this;
+  }
+
+  serialize(): Record<S, boolean> {
+    const Flags = (this.constructor as typeof BitField).Flags as Record<S, bigint>;
+    const serialized: Record<string, boolean> = {};
+    for (const [key, value] of Object.entries(Flags) as [S, bigint][]) {
+      serialized[key as string] = (this.bitfield & value) === value;
+    }
+    return serialized as Record<S, boolean>;
+  }
+
+  toArray(): S[] {
+    const Flags = (this.constructor as typeof BitField).Flags as Record<S, bigint>;
+    return (Object.entries(Flags) as [S, bigint][])
+      .filter(([, value]) => (this.bitfield & value) === value)
+      .map(([key]) => key);
+  }
+
+  toJSON() {
+    return this.bitfield.toString();
+  }
+
+  valueOf() {
+    return this.bitfield.toString();
+  }
+
+  equals(bitfield: BitField<S>): boolean {
+    return this.bitfield === bitfield.bitfield;
+  }
+
+  freeze(): Readonly<BitField<S>> {
+    return Object.freeze(this);
+  }
+}

package/core/packages/util/src/MessageFlagsBitField.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { MessageFlagsBitField, MessageFlagsBits } from './MessageFlagsBitField.js';
+
+describe('MessageFlagsBitField', () => {
+  it('creates with default 0', () => {
+    const bf = new MessageFlagsBitField();
+    expect(bf.bitfield).toBe(0n);
+  });
+
+  it('has checks SuppressEmbeds', () => {
+    const bf = new MessageFlagsBitField([MessageFlagsBits.SuppressEmbeds]);
+    expect(bf.has(MessageFlagsBits.SuppressEmbeds)).toBe(true);
+    expect(bf.has(MessageFlagsBits.VoiceMessage)).toBe(false);
+  });
+
+  it('add and remove', () => {
+    const bf = new MessageFlagsBitField()
+      .add(MessageFlagsBits.SuppressEmbeds)
+      .add(MessageFlagsBits.SuppressNotifications);
+    expect(bf.has(MessageFlagsBits.SuppressEmbeds)).toBe(true);
+    bf.remove(MessageFlagsBits.SuppressEmbeds);
+    expect(bf.has(MessageFlagsBits.SuppressEmbeds)).toBe(false);
+  });
+
+  it('serialize returns flags object', () => {
+    const bf = new MessageFlagsBitField([MessageFlagsBits.VoiceMessage]);
+    const s = bf.serialize();
+    expect(s.VoiceMessage).toBe(true);
+    expect(s.SuppressEmbeds).toBe(false);
+  });
+
+  it('toArray returns enabled flag names', () => {
+    const bf = new MessageFlagsBitField([
+      MessageFlagsBits.CompactAttachments,
+      MessageFlagsBits.SuppressEmbeds,
+    ]);
+    const arr = bf.toArray();
+    expect(arr).toContain('CompactAttachments');
+    expect(arr).toContain('SuppressEmbeds');
+    expect(arr).toHaveLength(2);
+  });
+});

package/core/packages/util/src/MessageFlagsBitField.ts

@@ -0,0 +1,20 @@
+import { BitField, type BitFieldResolvable } from './BitField.js';
+
+/**
+ * Message flag bit values matching the API MessageFlags schema (openapi.json).
+ * Format: int32.
+ */
+export const MessageFlagsBits = {
+  SuppressEmbeds: 1n << 2n, // 4
+  SuppressNotifications: 1n << 12n, // 4096
+  VoiceMessage: 1n << 13n, // 8192
+  CompactAttachments: 1n << 17n, // 131072
+} as const;
+
+export type MessageFlagsString = keyof typeof MessageFlagsBits;
+
+export class MessageFlagsBitField extends BitField<MessageFlagsString> {
+  static override Flags = MessageFlagsBits;
+}
+
+export type MessageFlagsResolvable = BitFieldResolvable<MessageFlagsString>;

package/core/packages/util/src/PermissionsBitField.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest';
+import {
+  resolvePermissionsToBitfield,
+  PermissionFlags,
+  PermissionsBitField,
+} from './PermissionsBitField.js';
+
+describe('resolvePermissionsToBitfield', () => {
+  it('returns string as-is when it looks like a number', () => {
+    expect(resolvePermissionsToBitfield('2048')).toBe('2048');
+    expect(resolvePermissionsToBitfield('8933636165185')).toBe('8933636165185');
+  });
+
+  it('resolves PermissionString to bitfield', () => {
+    expect(resolvePermissionsToBitfield('SendMessages')).toBe('2048');
+    expect(resolvePermissionsToBitfield('Administrator')).toBe('8');
+  });
+
+  it('resolves number to string', () => {
+    expect(resolvePermissionsToBitfield(2048)).toBe('2048');
+    expect(resolvePermissionsToBitfield(PermissionFlags.SendMessages)).toBe('2048');
+  });
+
+  it('resolves bigint to string', () => {
+    expect(resolvePermissionsToBitfield(2048n)).toBe('2048');
+  });
+
+  it('resolves array of permissions with OR', () => {
+    const result = resolvePermissionsToBitfield(['SendMessages', 'ViewChannel']);
+    expect(result).toBe(String(2048 | 1024)); // 3072
+  });
+
+  it('resolves PermissionsBitField instance', () => {
+    const bf = new PermissionsBitField([PermissionFlags.BanMembers]);
+    expect(resolvePermissionsToBitfield(bf)).toBe('4');
+  });
+
+  it('throws for invalid permission string', () => {
+    expect(() => resolvePermissionsToBitfield('InvalidPermission')).toThrow(RangeError);
+  });
+});
+
+describe('PermissionsBitField', () => {
+  it('uses the intended bit positions for high-bit permissions', () => {
+    expect(PermissionFlags.UseExternalStickers).toBe(1n << 37n);
+    expect(PermissionFlags.ModerateMembers).toBe(1n << 40n);
+    expect(PermissionFlags.CreateExpressions).toBe(1n << 43n);
+    expect(PermissionFlags.PinMessages).toBe(1n << 51n);
+    expect(PermissionFlags.BypassSlowmode).toBe(1n << 52n);
+    expect(PermissionFlags.UpdateRtcRegion).toBe(1n << 53n);
+  });
+
+  it('has checks single permission', () => {
+    const bf = new PermissionsBitField([PermissionFlags.SendMessages]);
+    expect(bf.has(PermissionFlags.SendMessages)).toBe(true);
+    expect(bf.has(PermissionFlags.BanMembers)).toBe(false);
+  });
+
+  it('has checks Administrator flag', () => {
+    const bf = new PermissionsBitField([PermissionFlags.Administrator]);
+    expect(bf.has(PermissionFlags.Administrator)).toBe(true);
+    expect(bf.has(PermissionFlags.BanMembers)).toBe(false);
+  });
+
+  it('toArray returns permission names', () => {
+    const bf = new PermissionsBitField([PermissionFlags.SendMessages, PermissionFlags.ViewChannel]);
+    const arr = bf.toArray();
+    expect(arr).toContain('SendMessages');
+    expect(arr).toContain('ViewChannel');
+    expect(arr.length).toBe(2);
+  });
+
+  it('serialize returns permission object', () => {
+    const bf = new PermissionsBitField([PermissionFlags.BanMembers]);
+    const s = bf.serialize();
+    expect(s.BanMembers).toBe(true);
+    expect(s.SendMessages).toBe(false);
+  });
+});

package/core/packages/util/src/PermissionsBitField.ts

@@ -0,0 +1,97 @@
+import { BitField, type BitFieldResolvable } from './BitField.js';
+
+/**
+ * Permission flags aligned with Fluxer API (fluxer_api/src/constants/Channel.ts).
+ * Bit positions use BigInt shifts (1n << n).
+ * Administrator (bit 3) implies all permissions. Guild owner bypasses role computation.
+ *
+ * @example
+ * if (member.permissions.has(PermissionFlags.BanMembers)) { ... }
+ * if (perms.has(PermissionFlags.Administrator)) { ... }
+ */
+export const PermissionFlags = {
+  CreateInstantInvite: 1n << 0n,
+  KickMembers: 1n << 1n,
+  BanMembers: 1n << 2n,
+  Administrator: 1n << 3n,
+  ManageChannels: 1n << 4n,
+  ManageGuild: 1n << 5n,
+  AddReactions: 1n << 6n,
+  ViewAuditLog: 1n << 7n,
+  PrioritySpeaker: 1n << 8n,
+  Stream: 1n << 9n,
+  ViewChannel: 1n << 10n,
+  SendMessages: 1n << 11n,
+  SendTtsMessages: 1n << 12n,
+  ManageMessages: 1n << 13n,
+  EmbedLinks: 1n << 14n,
+  AttachFiles: 1n << 15n,
+  ReadMessageHistory: 1n << 16n,
+  MentionEveryone: 1n << 17n,
+  UseExternalEmojis: 1n << 18n,
+  Connect: 1n << 20n,
+  Speak: 1n << 21n,
+  MuteMembers: 1n << 22n,
+  DeafenMembers: 1n << 23n,
+  MoveMembers: 1n << 24n,
+  UseVad: 1n << 25n,
+  ChangeNickname: 1n << 26n,
+  ManageNicknames: 1n << 27n,
+  ManageRoles: 1n << 28n,
+  ManageWebhooks: 1n << 29n,
+  ManageEmojisAndStickers: 1n << 30n,
+  ManageExpressions: 1n << 30n,
+  UseExternalStickers: 1n << 37n,
+  ModerateMembers: 1n << 40n,
+  CreateExpressions: 1n << 43n,
+  PinMessages: 1n << 51n,
+  BypassSlowmode: 1n << 52n,
+  UpdateRtcRegion: 1n << 53n,
+} as const;
+
+/** BigInt OR of all permission flags. Used for guild owner override (owner has all perms). */
+export const ALL_PERMISSIONS_BIGINT = Object.values(PermissionFlags).reduce((a, b) => a | b, 0n);
+
+export type PermissionString = keyof typeof PermissionFlags;
+
+export class PermissionsBitField extends BitField<PermissionString> {
+  static override Flags = PermissionFlags;
+}
+
+export type PermissionResolvable = BitFieldResolvable<PermissionString>;
+
+/**
+ * Resolve permission(s) to an API bitfield string. Uses BigInt to avoid overflow for flags > 2^31.
+ * @param perms - Permission string (e.g. "2048"), number, PermissionString, array of permissions, or PermissionsBitField
+ * @returns String bitfield for API (e.g. "8933636165185")
+ * @example
+ * resolvePermissionsToBitfield('2048'); // "2048"
+ * resolvePermissionsToBitfield(PermissionFlags.SendMessages); // "2048"
+ * resolvePermissionsToBitfield(['SendMessages', 'ViewChannel']); // combined bitfield
+ */
+export function resolvePermissionsToBitfield(perms: PermissionResolvable): string {
+  if (typeof perms === 'string') {
+    const num = Number(perms);
+    if (!Number.isNaN(num) && perms.trim() !== '') return perms;
+    const mapped = PermissionFlags[perms];
+    if (mapped !== undefined) return String(mapped);
+    throw new RangeError(`Invalid permission string: ${perms}`);
+  }
+  if (typeof perms === 'number') return String(perms);
+  if (typeof perms === 'bigint') return String(perms);
+  if (perms instanceof PermissionsBitField) return String(BigInt(perms.bitfield));
+  if (Array.isArray(perms)) {
+    let acc = 0n;
+    for (const p of perms) {
+      let v: bigint;
+      if (typeof p === 'number') v = BigInt(p);
+      else if (typeof p === 'string') {
+        const mapped = PermissionFlags[p];
+        v = mapped !== undefined ? BigInt(mapped) : BigInt(Number(p) || 0);
+      } else v = BigInt((p as PermissionsBitField).bitfield);
+      acc |= v;
+    }
+    return String(acc);
+  }
+  throw new RangeError(`Invalid permission resolvable: ${perms}`);
+}