@stacksjs/types 0.70.88 → 0.70.90

package/dist/oauth.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Type guard to check if a value is an AccessToken.
+ */
+export declare function isAccessToken(value: unknown): value is AccessToken;
+/**
+ * Type guard to check if a value is a PersonalAccessToken.
+ */
+export declare function isPersonalAccessToken(value: unknown): value is PersonalAccessToken;
+/**
+ * Type guard to check if a value is an OAuthClient.
+ */
+export declare function isOAuthClient(value: unknown): value is OAuthClient;
+/**
+ * Access token entity with full metadata.
+ * Represents a token after being retrieved from the database.
+ */
+export declare interface AccessToken {
+  readonly id: number
+  readonly userId: number
+  readonly clientId: number
+  readonly name: string
+  readonly scopes: TokenScopes
+  readonly revoked: boolean
+  readonly expiresAt: Date | null
+  readonly createdAt: Date
+  readonly updatedAt: Date
+}
+/**
+ * Personal access token with additional metadata.
+ * Extended version used in the Auth class.
+ */
+export declare interface PersonalAccessToken extends AccessToken {
+  readonly abilities: TokenScopes
+  readonly plainTextToken?: AuthToken
+}
+/**
+ * Mutable version of AccessToken for internal use.
+ */
+export declare interface MutableAccessToken {
+  id: number
+  userId: number
+  clientId: number
+  name: string
+  scopes: TokenScopes
+  revoked: boolean
+  expiresAt: Date | null
+  createdAt: Date
+  updatedAt: Date
+}
+/**
+ * Refresh token entity for obtaining new access tokens.
+ */
+export declare interface RefreshToken {
+  readonly id: number
+  readonly accessTokenId: number
+  readonly revoked: boolean
+  readonly expiresAt: Date | null
+  readonly createdAt: Date
+}
+/**
+ * OAuth client entity representing an authorized application.
+ */
+export declare interface OAuthClient {
+  readonly id: number
+  readonly name: string
+  readonly secret: ClientSecret | string
+  readonly provider: string | null
+  readonly redirect: string
+  readonly personalAccessClient: boolean
+  readonly passwordClient: boolean
+  readonly revoked: boolean
+  readonly createdAt: Date
+  readonly updatedAt: Date | null
+}
+/**
+ * Raw database row for oauth_access_tokens table.
+ * Use this when working with raw SQL queries.
+ */
+export declare interface OAuthAccessTokenRow {
+  id: number
+  user_id: number
+  oauth_client_id: number
+  token: string
+  name: string | null
+  scopes: string | null
+  revoked: boolean | number
+  expires_at: string | null
+  created_at: string | null
+  updated_at: string | null
+}
+/**
+ * Raw database row for oauth_refresh_tokens table.
+ */
+export declare interface OAuthRefreshTokenRow {
+  id: number
+  access_token_id: number
+  token: string
+  revoked: boolean | number
+  expires_at: string | null
+  created_at: string | null
+}
+/**
+ * Raw database row for oauth_clients table.
+ */
+export declare interface OAuthClientRow {
+  id: number
+  name: string
+  secret: string
+  provider: string | null
+  redirect: string
+  personal_access_client: boolean | number
+  password_client: boolean | number
+  revoked: boolean | number
+  created_at: string | null
+  updated_at: string | null
+}
+/**
+ * Options for creating a new token.
+ */
+export declare interface TokenCreateOptions {
+  name?: string
+  abilities?: TokenScopes
+  scopes?: TokenScopes
+  expiresAt?: Date
+  expiresInMinutes?: number
+  withRefreshToken?: boolean
+  refreshExpiresInDays?: number
+}
+/**
+ * Result returned when creating a personal access token.
+ */
+export declare interface PersonalAccessTokenResult {
+  readonly accessToken: AccessToken
+  readonly plainTextToken: AuthToken | string
+  readonly refreshToken?: RefreshTokenString | string
+  readonly expiresIn: number
+}
+/**
+ * Result returned when creating a token via the Auth class.
+ */
+export declare interface NewAccessToken {
+  readonly accessToken: PersonalAccessToken
+  readonly plainTextToken: AuthToken
+  readonly refreshToken?: string
+  readonly expiresIn?: number
+}
+/**
+ * Result returned when refreshing a token.
+ */
+export declare interface RefreshTokenResult {
+  readonly accessToken: AccessToken
+  readonly plainTextToken: AuthToken | string
+  readonly refreshToken: RefreshTokenString | string
+  readonly expiresIn: number
+}
+/**
+ * Options for creating a new OAuth client.
+ */
+export declare interface CreateClientOptions {
+  name: string
+  redirect: string
+  userId?: number
+  personalAccessClient?: boolean
+  passwordClient?: boolean
+  provider?: string
+}
+/**
+ * Result returned when creating a new OAuth client.
+ */
+export declare interface CreateClientResult {
+  readonly client: OAuthClient
+  readonly plainTextSecret: ClientSecret | string
+}
+/**
+ * Result of token validation.
+ */
+export declare interface TokenValidationResult {
+  readonly valid: boolean
+  readonly token?: AccessToken
+  readonly error?: string
+  readonly rotated?: boolean
+  readonly newToken?: AuthToken
+}
+/**
+ * Token payload extracted from JWT-like tokens.
+ */
+export declare interface TokenPayload {
+  readonly sub: number
+  readonly iat: number
+  readonly exp: number
+  readonly jti: string
+}
+/**
+ * User credentials for authentication.
+ */
+export declare interface AuthCredentials {
+  email?: string
+  password?: string
+  [key: string]: string | undefined
+}
+/**
+ * Login result containing user and token.
+ */
+export declare interface LoginResult<TUser = unknown> {
+  readonly user: TUser
+  readonly token: AuthToken
+}
+/**
+ * SQL syntax configuration based on database driver.
+ */
+export declare interface DatabaseSqlSyntax {
+  readonly now: string
+  readonly boolTrue: string
+  readonly boolFalse: string
+  readonly autoIncrement: string
+  readonly primaryKey: string
+  readonly param: (index: number) => string
+}
+/**
+ * Token with user attached.
+ */
+export declare interface TokenWithUser<TUser = unknown> extends AccessToken {
+  readonly user: TUser
+}
+/**
+ * Branded type for authentication tokens.
+ * Using a branded type ensures tokens are not accidentally confused with regular strings.
+ *
+ * @example
+ * ```typescript
+ * const token: AuthToken = 'abc123' as AuthToken
+ * // or use createAuthToken helper
+ * ```
+ */
+export type AuthToken = string & { readonly __brand: 'AuthToken' }
+/**
+ * Branded type for refresh tokens.
+ * Distinct from AuthToken to prevent accidental misuse.
+ */
+export type RefreshTokenString = string & { readonly __brand: 'RefreshToken' }
+/**
+ * Branded type for OAuth client secrets.
+ */
+export type ClientSecret = string & { readonly __brand: 'ClientSecret' }
+/**
+ * Branded type for hashed token values stored in database.
+ */
+export type HashedToken = string & { readonly __brand: 'HashedToken' }
+/**
+ * Common OAuth scopes/abilities.
+ * Use these predefined scopes or define custom ones.
+ */
+export type CommonScope = | '*' // Wildcard - all permissions
+  | 'read'
+  | 'write'
+  | 'delete'
+  | 'admin'
+  | 'user:read'
+  | 'user:write'
+  | 'posts:read'
+  | 'posts:write'
+  | 'posts:delete';
+/**
+ * Token scope - can be common scopes or custom string scopes.
+ */
+export type TokenScope = CommonScope | (string & {});
+/**
+ * Array of token scopes/abilities.
+ */
+export type TokenScopes = TokenScope[];
+/**
+ * OAuth client types for different authentication flows.
+ */
+export type OAuthClientType = 'personal_access' | 'password' | 'authorization_code' | 'client_credentials';
+/**
+ * Supported database drivers for OAuth tables.
+ */
+export type DatabaseDriver = 'postgres' | 'mysql' | 'sqlite';
+/**
+ * Make specific properties of a type optional.
+ */
+export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * Make specific properties of a type required.
+ */
+export type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+/**
+ * Extract the user type from a generic context.
+ */
+export type ExtractUser<T> = T extends { user: infer U } ? U : never;

package/dist/pages.d.ts

@@ -0,0 +1,10 @@
+export declare interface PagesOption {
+  onboarding: {
+    path: string
+    pages: string[]
+  }
+  settings: {
+    path: string
+    pages: string[]
+  }
+}

package/dist/payments.d.ts

@@ -0,0 +1,322 @@
+import type Stripe from 'stripe';
+// =============================================================================
+// Configuration Types
+// =============================================================================
+export declare interface PaymentOptions {
+  driver: 'stripe'
+  stripe: StripeConfig
+  currency?: string
+  webhook?: WebhookConfig
+}
+export declare interface StripeConfig {
+  publishableKey: string
+  secretKey: string
+  apiVersion?: string
+  webhookSecret?: string
+}
+export declare interface WebhookConfig {
+  secret: string
+  tolerance?: number
+}
+// =============================================================================
+// Customer Types
+// =============================================================================
+export declare interface StripeCustomerOptions {
+  address?: {
+    line1?: string
+    line2?: string
+    city?: string
+    state?: string
+    postal_code?: string
+    country?: string
+  }
+  name?: string
+  phone?: string
+  metadata?: Stripe.Emptyable<Stripe.MetadataParam>
+  email?: string
+  preferred_locales?: string[]
+}
+export declare interface CustomerOptions {
+  description?: string
+  address?: string
+  email?: string
+  metadata?: Record<string, string>
+  name?: string
+  payment_method?: string
+  shipping?: ShippingInfo
+  listOptions?: {
+    created?: Record<string, unknown>
+    ending_before?: string
+    limit?: number
+    starting_after?: string
+    test_clock?: string
+  }
+  searchOptions?: {
+    query?: string
+    limit?: number
+    page?: number
+  }
+}
+export declare interface ShippingInfo {
+  address: {
+    line1: string
+    line2?: string
+    city?: string
+    state?: string
+    postal_code?: string
+    country?: string
+  }
+  name: string
+  phone?: string
+}
+// =============================================================================
+// Charge Types
+// =============================================================================
+export declare interface ChargeOptions {
+  currency?: string
+  source?: string
+  description?: string
+  chargeId?: string
+  limit?: number
+  metadata?: Record<string, string>
+  searchOptions?: {
+    query?: string
+    limit?: number
+  }
+}
+export declare interface ChargeResult {
+  id: string
+  amount: number
+  currency: string
+  status: 'succeeded' | 'pending' | 'failed'
+  paymentMethod?: string
+  receiptUrl?: string
+  refunded: boolean
+  refundedAmount?: number
+}
+// =============================================================================
+// Checkout Types
+// =============================================================================
+export declare interface CheckoutLineItem {
+  priceId: string
+  quantity: number
+}
+export declare interface CheckoutOptions extends Partial<Stripe.Checkout.SessionCreateParams> {
+  enableTax?: boolean
+  allowPromotions?: boolean
+}
+export declare interface CheckoutSessionResult {
+  id: string
+  url: string | null
+  status: string
+  customerId?: string
+  subscriptionId?: string
+  paymentIntentId?: string
+}
+// =============================================================================
+// Subscription Types
+// =============================================================================
+export declare interface SubscriptionOptions {
+  type: string
+  lookupKey: string
+  trialDays?: number
+  coupon?: string
+  metadata?: Record<string, string>
+}
+export declare interface SubscriptionResult {
+  id: string
+  status: SubscriptionStatus
+  currentPeriodEnd: Date
+  cancelAtPeriodEnd: boolean
+  items: SubscriptionItem[]
+  latestInvoiceId?: string
+}
+export declare interface SubscriptionItem {
+  id: string
+  priceId: string
+  productId: string
+  quantity: number
+}
+// =============================================================================
+// Invoice Types
+// =============================================================================
+export declare interface InvoiceResult {
+  id: string
+  number: string | null
+  status: InvoiceStatus
+  amountDue: number
+  amountPaid: number
+  currency: string
+  dueDate: Date | null
+  paidAt: Date | null
+  hostedInvoiceUrl: string | null
+  pdfUrl: string | null
+}
+// =============================================================================
+// Payment Method Types
+// =============================================================================
+export declare interface PaymentMethodResult {
+  id: string
+  type: PaymentMethodType
+  card?: CardDetails
+  isDefault: boolean
+}
+export declare interface CardDetails {
+  brand: string
+  last4: string
+  expMonth: number
+  expYear: number
+  funding: 'credit' | 'debit' | 'prepaid' | 'unknown'
+}
+// =============================================================================
+// Product & Price Types
+// =============================================================================
+export declare interface ProductOptions {
+  name: string
+  description?: string
+  images?: string[]
+  metadata?: Record<string, string>
+  active?: boolean
+}
+export declare interface PriceOptions {
+  productId: string
+  unitAmount: number
+  currency?: string
+  recurring?: {
+    interval: 'day' | 'week' | 'month' | 'year'
+    intervalCount?: number
+  }
+  lookupKey?: string
+  metadata?: Record<string, string>
+}
+// =============================================================================
+// Coupon Types
+// =============================================================================
+export declare interface CouponOptions {
+  id?: string
+  name?: string
+  percentOff?: number
+  amountOff?: number
+  currency?: string
+  duration: 'forever' | 'once' | 'repeating'
+  durationInMonths?: number
+  maxRedemptions?: number
+  redeemBy?: Date
+}
+export declare interface PromotionCodeOptions {
+  couponId: string
+  code: string
+  maxRedemptions?: number
+  expiresAt?: Date
+  firstTimeTransaction?: boolean
+  minimumAmount?: number
+  minimumAmountCurrency?: string
+}
+export declare interface WebhookEvent<T = unknown> {
+  id: string
+  type: WebhookEventType
+  data: {
+    object: T
+    previousAttributes?: Partial<T>
+  }
+  created: number
+  livemode: boolean
+}
+export declare interface WebhookHandlerResult {
+  handled: boolean
+  eventType: string
+  error?: string
+}
+// =============================================================================
+// Dispute Types
+// =============================================================================
+export declare interface DisputeOptions {
+  dp_id?: string
+  metadata?: Record<string, string>
+  listOptions?: {
+    charge?: string
+    payment_intent?: string
+    created?: string
+    ending_before?: string
+    limit?: number
+    starting_after?: string
+  }
+}
+// =============================================================================
+// Event Types
+// =============================================================================
+export declare interface EventOptions {
+  event_id?: string
+  listOptions?: {
+    created?: Record<string, unknown>
+    delivery_success?: boolean
+    ending_before?: string
+    limit?: number
+    starting_after?: string
+    type?: string
+  }
+}
+// =============================================================================
+// Utility Types
+// =============================================================================
+export declare interface PaginatedResult<T> {
+  data: T[]
+  hasMore: boolean
+  totalCount?: number
+}
+export declare interface AmountBreakdown {
+  subtotal: number
+  tax: number
+  discount: number
+  total: number
+  currency: string
+}
+export type PaymentConfig = Partial<PaymentOptions>;
+export type SubscriptionStatus = | 'active'
+  | 'canceled'
+  | 'incomplete'
+  | 'incomplete_expired'
+  | 'past_due'
+  | 'paused'
+  | 'trialing'
+  | 'unpaid';
+export type InvoiceStatus = | 'draft'
+  | 'open'
+  | 'paid'
+  | 'uncollectible'
+  | 'void';
+export type PaymentMethodType = | 'card'
+  | 'bank_account'
+  | 'sepa_debit'
+  | 'ideal'
+  | 'sofort'
+  | 'giropay';
+// =============================================================================
+// Webhook Types
+// =============================================================================
+export type WebhookEventType = | 'payment_intent.succeeded'
+  | 'payment_intent.payment_failed'
+  | 'payment_intent.created'
+  | 'payment_intent.canceled'
+  | 'customer.subscription.created'
+  | 'customer.subscription.updated'
+  | 'customer.subscription.deleted'
+  | 'customer.subscription.trial_will_end'
+  | 'customer.created'
+  | 'customer.updated'
+  | 'customer.deleted'
+  | 'invoice.paid'
+  | 'invoice.payment_failed'
+  | 'invoice.finalized'
+  | 'invoice.created'
+  | 'checkout.session.completed'
+  | 'checkout.session.expired'
+  | 'charge.succeeded'
+  | 'charge.failed'
+  | 'charge.refunded'
+  | 'charge.dispute.created'
+  | 'charge.dispute.closed'
+  | 'payment_method.attached'
+  | 'payment_method.detached'
+  | 'setup_intent.succeeded'
+  | 'setup_intent.setup_failed';

package/dist/phone.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Phone/Voice Service Configuration Types
+ * Powered by Amazon Connect
+ */
+export declare interface PhoneNumberConfig {
+  type: 'TOLL_FREE' | 'DID' | 'UIFN'
+  countryCode: string
+  description?: string
+  contactFlowId?: string
+  notifyOnCall?: string[]
+}
+export declare interface PhoneNotificationConfig {
+  enabled: boolean
+  channels: ('email' | 'sms' | 'slack' | 'webhook')[]
+  webhookUrl?: string
+  slackChannel?: string
+}
+export declare interface BusinessHoursSchedule {
+  day: 'SUNDAY' | 'MONDAY' | 'TUESDAY' | 'WEDNESDAY' | 'THURSDAY' | 'FRIDAY' | 'SATURDAY'
+  start: string
+  end: string
+}
+export declare interface BusinessHoursConfig {
+  timezone: string
+  schedule: BusinessHoursSchedule[]
+}
+export declare interface VoicemailConfig {
+  enabled: boolean
+  transcription: boolean
+  maxDurationSeconds: number
+  greeting?: string
+}
+export declare interface PhoneInstanceConfig {
+  alias: string
+  inboundCallsEnabled: boolean
+  outboundCallsEnabled: boolean
+}
+export declare interface PhoneNotificationsConfig {
+  incomingCall?: PhoneNotificationConfig
+  missedCall?: PhoneNotificationConfig
+  voicemail?: PhoneNotificationConfig
+}
+export declare interface CallForwardingRule {
+  name: string
+  condition: CallForwardingCondition
+  forwardTo: string
+  ringTimeout: number
+  priority: number
+}
+export declare interface CallForwardingConfig {
+  enabled: boolean
+  rules: CallForwardingRule[]
+}
+export declare interface PhoneOptions {
+  enabled: boolean
+  provider: 'connect'
+  instance?: PhoneInstanceConfig
+  phoneNumbers: PhoneNumberConfig[]
+  notifications: PhoneNotificationsConfig
+  voicemail: VoicemailConfig
+  forwarding?: CallForwardingConfig
+  businessHours?: BusinessHoursConfig
+}
+export type CallForwardingCondition = 'always' | 'business_hours' | 'after_hours';
+export type PhoneConfig = Partial<PhoneOptions>;

package/dist/ports.d.ts

@@ -0,0 +1,20 @@
+/**
+ * **Stacks Ports**
+ *
+ * This port is used by the Stacks servers when running your application, library, email services,
+ * and other services. You may change this port to any other port that is free
+ * on your machine, as long as the following 6 ports are also available.
+ */
+export declare interface Ports {
+  frontend: number
+  backend: number
+  admin: number
+  library: number
+  desktop: number
+  email: number
+  docs: number
+  inspect: number
+  api: number
+  systemTray: number
+  database: number
+}

package/dist/promise.d.ts

@@ -0,0 +1 @@
+export type MaybePromise<T> = T | Promise<T>;