@stacksjs/types 0.70.23 → 0.70.25

package/src/sms.ts

@@ -1,5 +1,265 @@
-// import type { ISmsOptions as SmsOptions } from '@novu/stateless'
+/**
+ * SMS Service Configuration Types
+ * Supports Twilio, Vonage, and AWS providers
+ */
 
-// export type { SmsOptions }
+// =============================================================================
+// Core SMS Types
+// =============================================================================
 
-// export type SmsConfig = SmsOptions
+export type SmsProvider = 'twilio' | 'vonage' | 'pinpoint' | 'sns'
+
+export interface SmsMessage {
+  /**
+   * Recipient phone number (E.164 format recommended)
+   */
+  to: string | string[]
+
+  /**
+   * Message body
+   */
+  body: string
+
+  /**
+   * Sender ID or phone number
+   */
+  from?: string
+
+  /**
+   * Optional media URLs (MMS)
+   */
+  mediaUrls?: string[]
+
+  /**
+   * Callback URL for status updates
+   */
+  statusCallback?: string
+
+  /**
+   * Additional provider-specific options
+   */
+  options?: Record<string, unknown>
+}
+
+export interface SmsSendResult {
+  success: boolean
+  messageId?: string
+  status?: SmsStatus
+  to: string
+  error?: string
+  provider: SmsProvider
+  segments?: number
+  price?: number
+  currency?: string
+}
+
+export type SmsStatus =
+  | 'queued'
+  | 'sending'
+  | 'sent'
+  | 'delivered'
+  | 'failed'
+  | 'undelivered'
+  | 'unknown'
+
+export interface SmsStatusUpdate {
+  messageId: string
+  to: string
+  status: SmsStatus
+  timestamp: Date
+  errorCode?: string
+  errorMessage?: string
+}
+
+// =============================================================================
+// Provider Configurations
+// =============================================================================
+
+export interface TwilioConfig {
+  accountSid: string
+  authToken: string
+  from?: string
+  messagingServiceSid?: string
+  statusCallback?: string
+}
+
+export interface VonageConfig {
+  apiKey: string
+  apiSecret: string
+  from?: string
+  applicationId?: string
+  privateKey?: string
+}
+
+export interface AwsSmsConfig {
+  region: string
+  accessKeyId?: string
+  secretAccessKey?: string
+  senderId?: string
+  originationNumber?: string
+}
+
+// =============================================================================
+// SMS Options (Main Config)
+// =============================================================================
+
+export interface SmsTemplateConfig {
+  name: string
+  body: string
+  variables?: string[]
+}
+
+export interface SmsOptOutConfig {
+  enabled: boolean
+  keywords: string[]
+}
+
+export interface SmsTwoWayConfig {
+  enabled: boolean
+  webhookUrl?: string
+  snsTopicArn?: string
+}
+
+export interface SmsInboxConfig {
+  enabled: boolean
+  bucket: string
+  prefix?: string
+  retentionDays?: number
+}
+
+export interface SmsOptions {
+  /**
+   * Enable SMS functionality
+   */
+  enabled: boolean
+
+  /**
+   * Default SMS provider
+   */
+  provider: SmsProvider
+
+  /**
+   * Default sender ID or phone number
+   */
+  from?: string
+
+  /**
+   * Default country code for phone number formatting
+   */
+  defaultCountryCode?: string
+
+  /**
+   * Message type (affects pricing and delivery)
+   */
+  messageType?: 'TRANSACTIONAL' | 'PROMOTIONAL'
+
+  /**
+   * Provider-specific configurations
+   */
+  drivers: {
+    twilio?: TwilioConfig
+    vonage?: VonageConfig
+    pinpoint?: AwsSmsConfig
+    sns?: AwsSmsConfig
+  }
+
+  /**
+   * Opt-out handling configuration
+   */
+  optOut?: SmsOptOutConfig
+
+  /**
+   * Two-way messaging configuration
+   */
+  twoWay?: SmsTwoWayConfig
+
+  /**
+   * Message templates
+   */
+  templates?: SmsTemplateConfig[]
+
+  /**
+   * Inbox configuration for storing received messages
+   */
+  inbox?: SmsInboxConfig
+
+  /**
+   * Max monthly spend limit
+   */
+  maxSpendPerMonth?: number
+}
+
+export type SmsConfig = Partial<SmsOptions>
+
+// =============================================================================
+// SMS Driver Interface
+// =============================================================================
+
+export interface SmsDriver {
+  /**
+   * Send an SMS message
+   */
+  send(message: SmsMessage): Promise<SmsSendResult>
+
+  /**
+   * Send multiple SMS messages
+   */
+  sendBulk(messages: SmsMessage[]): Promise<SmsSendResult[]>
+
+  /**
+   * Get message status
+   */
+  getStatus?(messageId: string): Promise<SmsStatusUpdate>
+
+  /**
+   * Verify a phone number
+   */
+  verify?(phoneNumber: string): Promise<{ valid: boolean, carrier?: string, type?: string }>
+
+  /**
+   * Get account balance/usage
+   */
+  getBalance?(): Promise<{ balance: number, currency: string }>
+}
+
+// =============================================================================
+// Verification Types (for 2FA/OTP)
+// =============================================================================
+
+export interface VerificationRequest {
+  to: string
+  channel?: 'sms' | 'call' | 'whatsapp'
+  codeLength?: number
+  locale?: string
+  customMessage?: string
+}
+
+export interface VerificationResult {
+  success: boolean
+  verificationId?: string
+  status: 'pending' | 'approved' | 'denied' | 'expired'
+  error?: string
+}
+
+export interface VerificationCheckRequest {
+  verificationId?: string
+  to: string
+  code: string
+}
+
+export interface SmsVerificationDriver {
+  /**
+   * Start a verification (send OTP)
+   */
+  startVerification(request: VerificationRequest): Promise<VerificationResult>
+
+  /**
+   * Check a verification code
+   */
+  checkVerification(request: VerificationCheckRequest): Promise<VerificationResult>
+
+  /**
+   * Cancel a pending verification
+   */
+  cancelVerification?(verificationId: string): Promise<boolean>
+}

package/src/stack-extensions.ts

@@ -0,0 +1,184 @@
+/**
+ * Known top-level directories in a Stacks project that a stack extension can provide.
+ * Uses `(string & {})` to allow custom directories while still providing autocomplete.
+ */
+export type StackDirectory =
+  | 'app'
+  | 'config'
+  | 'database'
+  | 'resources'
+  | 'routes'
+  | 'public'
+  | 'locales'
+  | 'docs'
+  | (string & {})
+
+// ─── Stack Extensions Registry ──────────────────────────────────────────────
+//
+// This is the central registry of known stack extensions. Third-party authors
+// can submit a PR to add their stack here. Once merged, all Stacks users get
+// autocomplete and type safety for the new stack name.
+//
+// To add your stack, add a new entry below following the pattern:
+//   'your-stack-name': { package: '@your-org/your-stack', description: '...' },
+//
+// Requirements for PRs:
+//   - The package must be published to npm
+//   - The package.json must contain a valid `stacks` field with a `name`
+//   - The description should be concise (under 80 chars)
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface StackRegistryEntry {
+  /** The npm package name */
+  package: string
+  /** A short description of what this stack provides */
+  description: string
+  /** GitHub repository (e.g. 'stacksjs/blog-stack') */
+  github?: string
+}
+
+/**
+ * The central registry of known stack extensions.
+ *
+ * Third-party stack authors: submit a PR to add your stack here.
+ * Once merged, all Stacks users will get autocomplete for your stack name.
+ */
+export const stackExtensionRegistry = {
+  // ── Community Stacks ────────────────────────────────────────────────────
+  // Add your stack here via PR! Follow the pattern:
+  //   'your-stack': { package: '@your-org/your-stack', description: 'What it does' },
+  //
+  // Once merged, all Stacks users get autocomplete for your stack name.
+} as const satisfies Record<string, StackRegistryEntry>
+
+/**
+ * All known stack extension names, derived from the registry.
+ * Uses `(string & {})` to also accept any custom/unregistered stack name.
+ */
+export type KnownStackName = keyof typeof stackExtensionRegistry | (string & {})
+
+/**
+ * Metadata for a stack extension, defined in the `stacks` field of a stack's package.json.
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "@stacksjs/blog",
+ *   "stacks": {
+ *     "name": "blog",
+ *     "description": "Blog functionality for Stacks",
+ *     "directories": ["app", "config", "database", "resources"]
+ *   }
+ * }
+ * ```
+ */
+export interface StackMeta {
+  /** Short identifier for the stack (e.g. 'blog', 'commerce') */
+  name: KnownStackName
+  /** Human-readable description of what this stack provides */
+  description?: string
+  /** Semver version of the stack */
+  version?: string
+  /** Which top-level directories this stack provides. Defaults to all known directories if omitted. */
+  directories?: StackDirectory[]
+  /** Lifecycle hooks that run during install/uninstall */
+  hooks?: {
+    preInstall?: string
+    postInstall?: string
+    preUninstall?: string
+    postUninstall?: string
+  }
+}
+
+export type ConflictStrategy = 'skip' | 'overwrite' | 'backup'
+
+/** Tracks a single installed stack in the lock file */
+export interface StackManifestEntry {
+  /** The npm package name (e.g. '@stacksjs/blog') */
+  packageName: string
+  /** The stack's short name */
+  name: string
+  /** Installed version */
+  version: string
+  /** ISO timestamp of when this stack was installed */
+  installedAt: string
+  /** All files that were copied into the project, relative to project root */
+  files: string[]
+  /** Files that were skipped due to conflicts */
+  skipped: string[]
+  /** The conflict strategy used during this install */
+  conflictStrategy: ConflictStrategy
+}
+
+/** The stacks.lock.json file format */
+export interface StackLock {
+  version: 1
+  generatedAt: string
+  stacks: Record<string, StackManifestEntry>
+}
+
+export interface StackInstallOptions {
+  /** The stack name or package name to install */
+  name: KnownStackName
+  /** How to handle file conflicts. Defaults to 'skip'. */
+  conflict?: ConflictStrategy
+  /** Force overwrite all files (shorthand for conflict: 'overwrite') */
+  force?: boolean
+  /** Show what would happen without making changes */
+  dryRun?: boolean
+  /** Enable verbose output */
+  verbose?: boolean
+}
+
+export interface StackUninstallOptions {
+  /** The stack name or package name to uninstall */
+  name: KnownStackName
+  /** Force removal even if files were modified after install */
+  force?: boolean
+  /** Enable verbose output */
+  verbose?: boolean
+}
+
+/** Display format for the `stack:list` command */
+export interface StackListEntry {
+  name: string
+  packageName: string
+  version: string
+  description?: string
+  installed: boolean
+  installedAt?: string
+  fileCount?: number
+}
+
+/**
+ * A stack extension entry in the registry (`config/stacks.ts`).
+ *
+ * Can be either:
+ * - A string (the stack name or package name)
+ * - A full object with name, URL, and GitHub repository
+ *
+ * @example
+ * ```ts
+ * export default [
+ *   'blog',                                    // shorthand — autocomplete from registry
+ *   '@stacksjs/commerce',                      // scoped package shorthand
+ *   { name: 'analytics', github: 'stacksjs/analytics-stack' },
+ * ] satisfies StackExtensionRegistry
+ * ```
+ */
+export interface StackExtensionEntry {
+  /** The stack name or package name */
+  name: KnownStackName
+  /** The stack's website URL */
+  url?: string
+  /** GitHub repository (e.g. 'stacksjs/blog-stack') */
+  github?: string
+  /** npm package name if different from the name */
+  package?: string
+}
+
+/**
+ * The registry type for `config/stacks.ts`.
+ * Accepts both string shorthands and full objects.
+ */
+export type StackExtensionRegistry = (KnownStackName | StackExtensionEntry)[]

package/src/stacks.ts

@@ -2,14 +2,17 @@ import type {
   AiConfig,
   AnalyticsConfig,
   AppConfig,
+  AuthConfig,
   BinaryConfig,
   CacheConfig,
   CloudConfig,
+  DashboardConfig,
   DatabaseConfig,
   DnsConfig,
   DocsConfig,
   EmailConfig,
   ErrorConfig,
+  FilesystemsConfig,
   GitConfig,
   HashingConfig,
   LibraryConfig,
@@ -18,11 +21,11 @@ import type {
   PaymentConfig,
   Ports,
   QueueConfig,
+  RealtimeConfig,
   SaasConfig,
   SearchEngineConfig,
   SecurityConfig,
   ServicesConfig,
-  StorageConfig,
   Team,
   UiConfig,
 } from '.'
@@ -55,6 +58,24 @@ export interface StacksOptions {
    */
   app: AppConfig
 
+  /**
+   * **Auth Options**
+   *
+   * This configuration defines all of your Auth options. Because Stacks is fully-typed, you
+   * may hover any of the options below and the definitions will be provided. In case
+   * you have any questions, feel free to reach out via Discord or GitHub Discussions.
+   */
+  auth: AuthConfig
+
+  /**
+   * **Realtime Options**
+   *
+   * This configuration defines all of your Realtime options. Because Stacks is fully-typed,
+   * you may hover any of the options below and the definitions will be provided. In case
+   * you have any questions, feel free to reach out via Discord or GitHub Discussions.
+   */
+  realtime: RealtimeConfig
+
   /**
    * **Cache Options**
    *
@@ -82,6 +103,15 @@ export interface StacksOptions {
    */
   cloud: CloudConfig
 
+  /**
+   * **Dashboard Options**
+   *
+   * Controls which sections render in the `buddy dev --dashboard` sidebar.
+   * Set per-section `enabled` flags to `false` to hide a section that this
+   * project doesn't use (e.g. `commerce.enabled: false`).
+   */
+  dashboard: DashboardConfig
+
   /**
    * **Database Options**
    *
@@ -236,13 +266,13 @@ export interface StacksOptions {
   services: ServicesConfig
 
   /**
-   * **Storage Options**
+   * **Filesystems Options**
    *
-   * This configuration defines all of your Storage options. Because Stacks is fully-typed,
+   * This configuration defines all of your Filesystem options. Because Stacks is fully-typed,
    * you may hover any of the options below and the definitions will be provided. In case
    * you have any questions, feel free to reach out via Discord or GitHub Discussions.
    */
-  storage: StorageConfig
+  filesystems: FilesystemsConfig
 
   /**
    * **Team Members**

package/src/storage.ts

@@ -1,5 +1,71 @@
-import type { ChecksumOptions, DirectoryListing, FileContents, MimeTypeOptions, PublicUrlOptions, StatEntry, TemporaryUrlOptions } from '@flystorage/file-storage'
 import type { Buffer } from 'node:buffer'
+import type { ReadableStream } from 'node:stream/web'
+
+/**
+ * File contents can be a string, Buffer, Uint8Array, or ReadableStream
+ */
+export type FileContents = string | Buffer | Uint8Array | ReadableStream
+
+/**
+ * Visibility options for files
+ */
+export type Visibility = 'public' | 'private'
+
+/**
+ * File stat entry information
+ */
+export interface StatEntry {
+  path: string
+  type: 'file' | 'directory'
+  visibility: Visibility
+  size: number
+  lastModified: number
+  mimeType?: string
+  metadata?: Record<string, any>
+}
+
+/**
+ * Directory listing entry
+ */
+export interface DirectoryEntry {
+  path: string
+  type: 'file' | 'directory'
+}
+
+/**
+ * Directory listing iterator
+ */
+export interface DirectoryListing extends AsyncIterable<DirectoryEntry> {
+  [Symbol.asyncIterator](): AsyncIterator<DirectoryEntry>
+}
+
+/**
+ * Options for generating public URLs
+ */
+export interface PublicUrlOptions {
+  domain?: string
+}
+
+/**
+ * Options for generating temporary URLs
+ */
+export interface TemporaryUrlOptions {
+  expiresIn: number | Date
+}
+
+/**
+ * Checksum algorithm options
+ */
+export interface ChecksumOptions {
+  algorithm?: 'md5' | 'sha1' | 'sha256'
+}
+
+/**
+ * MIME type detection options
+ */
+export interface MimeTypeOptions {
+  useExtension?: boolean
+}
 
 export interface StorageOptions {
   /**
@@ -7,18 +73,86 @@ export interface StorageOptions {
    *
    * The storage driver to utilize.
    *
-   * @default string 's3'
-   * @see https://stacksjs.org/docs/storage
+   * @default 'local'
+   * @see https://stacksjs.com/docs/storage
+   */
+  driver: 's3' | 'efs' | 'local' | 'bun' | 'memory'
+
+  /**
+   * **Root Directory**
+   *
+   * Root directory for local and bun drivers.
+   *
+   * @default process.cwd()
+   */
+  root?: string
+
+  /**
+   * **S3 Configuration**
+   */
+  s3?: {
+    /**
+     * S3 bucket name
+     */
+    bucket: string
+
+    /**
+     * S3 region
+     *
+     * @default 'us-east-1'
+     */
+    region?: string
+
+    /**
+     * Key prefix for all S3 objects
+     */
+    prefix?: string
+
+    /**
+     * AWS credentials
+     */
+    credentials?: {
+      accessKeyId: string
+      secretAccessKey: string
+    }
+
+    /**
+     * Custom endpoint (for S3-compatible services)
+     */
+    endpoint?: string
+  }
+
+  /**
+   * **Public URL Configuration**
+   */
+  publicUrl?: {
+    /**
+     * Domain for public URLs
+     *
+     * @default 'http://localhost'
+     */
+    domain?: string
+  }
+
+  /**
+   * **Default Visibility**
+   *
+   * @default 'private'
    */
-  driver: 's3' | 'efs' | 'local'
+  defaultVisibility?: Visibility
 }
 
 export type StorageConfig = Partial<StorageOptions>
 
+/**
+ * Filesystem configuration (Laravel-style alias)
+ */
+export type FilesystemsConfig = StorageConfig
+
 export interface StorageDriver {
   list: (path: string, options?: any) => DirectoryListing
-  changeVisibility: (path: string, visibility: string) => Promise<void>
-  visibility: (path: string) => Promise<string>
+  changeVisibility: (path: string, visibility: Visibility) => Promise<void>
+  visibility: (path: string) => Promise<Visibility>
   fileExists: (path: string) => Promise<boolean>
   directoryExists: (path: string) => Promise<boolean>
   publicUrl: (path: string, options: PublicUrlOptions) => Promise<string>

package/src/table-names.ts

@@ -1 +1 @@
-export type TableNames = 'projects' | 'subscriber_emails' | 'personal_access_tokens' | 'team_users' | 'teams' | 'subscribers' | 'deployments' | 'releases' | 'team_users' | 'users' | 'posts' | 'print_devices' | 'categories' | 'payments' | 'drivers' | 'waitlist_products' | 'digital_deliveries' | 'manufacturers' | 'order_items' | 'shipping_zones' | 'customers' | 'products' | 'receipts' | 'product_variants' | 'license_keys' | 'waitlist_restaurants' | 'reviews' | 'product_units' | 'gift_cards' | 'orders' | 'coupons' | 'tax_rates' | 'transactions' | 'loyalty_points' | 'product_items' | 'loyalty_rewards' | 'shipping_methods' | 'shipping_rates' | 'delivery_routes' | 'failed_jobs' | 'payment_methods' | 'payment_transactions' | 'requests' | 'jobs' | 'subscriptions' | 'payment_products' | 'errors'
+export type TableNames = 'tags' | 'taggables' | 'categorizables' | 'comments' | 'commentables' | 'commentable_upvotes' | 'passkeys' | 'password_resets' | 'query_logs' | 'migrations' | 'tags' | 'payment_products' | 'failed_jobs' | 'social_posts' | 'payment_methods' | 'campaigns' | 'payment_transactions' | 'requests' | 'activities' | 'email_lists' | 'notifications' | 'jobs' | 'logs' | 'subscriptions' | 'errors' | 'comments' | 'users' | 'websockets' | 'pages' | 'authors' | 'posts' | 'print_devices' | 'categories' | 'payments' | 'drivers' | 'waitlist_products' | 'digital_deliveries' | 'manufacturers' | 'order_items' | 'shipping_zones' | 'customers' | 'products' | 'receipts' | 'product_variants' | 'license_keys' | 'waitlist_restaurants' | 'reviews' | 'product_units' | 'gift_cards' | 'orders' | 'coupons' | 'tax_rates' | 'transactions' | 'loyalty_points' | 'loyalty_rewards' | 'shipping_methods' | 'shipping_rates' | 'carts' | 'delivery_routes' | 'cart_items' | 'subscribers' | 'subscriber_emails'