@avelonjs/core 0.1.0

package/src/drivers/identity.ts

@@ -0,0 +1,133 @@
+import type { CapabilityMembers, CapabilitySurface, DriverContract } from './common'
+
+/** Literal identity features used to narrow the authentication facade. */
+export interface IdentityCapabilities<TFactor extends string = string> {
+  /** Whether password registration and sign-in are available. */
+  readonly passwords: boolean
+  /** Whether passwordless magic links are available. */
+  readonly magicLinks: boolean
+  /** Whether OAuth identities may be linked. */
+  readonly oauth: boolean
+  /** Whether organization membership is available. */
+  readonly organizations: boolean
+  /** Supported factors retained as a literal readonly list; empty means no MFA surface. */
+  readonly mfa: readonly TFactor[]
+}
+
+/** Authentication capability alias matching the application-facing `Auth` vocabulary. */
+export type AuthCapabilities<TFactor extends string = string> = IdentityCapabilities<TFactor>
+
+/** Organization summary returned by organization-capable identity drivers. */
+export interface IdentityOrganization {
+  /** Stable organization identifier. */
+  id: string
+  /** Display name. */
+  name: string
+}
+
+/** Multi-factor challenge issued by an identity driver. */
+export interface MfaChallenge<TFactor extends string = string> {
+  /** Stable challenge identifier. */
+  id: string
+  /** Framework-neutral factor kind. */
+  factor: TFactor
+  /** Time after which the challenge is invalid. */
+  expiresAt: Date
+}
+
+/**
+ * Base identity contract available independently of optional sign-in features. The driver factory
+ * receives `RequestCookies` through `avelon.config.ts` wiring, allowing `user`, `session`, and
+ * `signOut` to access request cookies without adapter imports or context parameters.
+ */
+export interface IdentityDriver<
+  TCapabilities extends IdentityCapabilities = IdentityCapabilities,
+  TRaw = unknown,
+  TActor = unknown,
+  TSession = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Returns the current actor or null when the request is anonymous. */
+  user(): Promise<TActor | null>
+  /** Returns the current session or null when no session exists. */
+  session(): Promise<TSession | null>
+  /** Ends the current session. */
+  signOut(): Promise<void>
+}
+
+/** Identity driver alias matching the application-facing `Auth` vocabulary. */
+export type AuthDriver<
+  TCapabilities extends IdentityCapabilities = IdentityCapabilities,
+  TRaw = unknown,
+  TActor = unknown,
+  TSession = unknown,
+> = IdentityDriver<TCapabilities, TRaw, TActor, TSession>
+
+/** Password operations exposed only by password-capable identity drivers. */
+export interface PasswordIdentitySurface<TActor = unknown> {
+  /** Registers an actor with an email address and password. */
+  register(email: string, password: string): Promise<TActor>
+  /** Authenticates an actor with an email address and password. */
+  signInWithPassword(email: string, password: string): Promise<TActor>
+  /** Sends a password-reset request without revealing account existence. */
+  sendPasswordReset(email: string): Promise<void>
+  /** Replaces a password after validating a password-recovery token. */
+  resetPassword(token: string, password: string): Promise<void>
+  /** Changes the current actor's password. */
+  updatePassword(password: string): Promise<void>
+}
+
+/** Passwordless operations exposed only by magic-link-capable identity drivers. */
+export interface MagicLinkIdentitySurface {
+  /** Sends a sign-in link to an email address. */
+  sendMagicLink(email: string, redirectTo?: string): Promise<void>
+}
+
+/** OAuth linking exposed only when the identity driver supports linked identities. */
+export interface OAuthIdentitySurface {
+  /** Links a completed social authorization to the current actor. */
+  linkOAuthIdentity(provider: string, code: string): Promise<void>
+}
+
+/** Organization operations exposed only by organization-capable identity drivers. */
+export interface OrganizationIdentitySurface {
+  /** Lists organizations available to the current actor. */
+  organizations(): Promise<readonly IdentityOrganization[]>
+  /** Selects the active organization for the current session. */
+  useOrganization(id: string): Promise<void>
+}
+
+/** Multi-factor operations exposed only by drivers declaring at least one factor. */
+export interface MfaIdentitySurface<TFactor extends string = string> {
+  /** Begins a multi-factor challenge for the current actor. */
+  challengeMfa(factor?: TFactor): Promise<MfaChallenge<TFactor>>
+  /** Verifies a challenge response and completes the pending authentication. */
+  verifyMfa(challengeId: string, code: string): Promise<void>
+}
+
+type ActorOf<TDriver extends IdentityDriver> =
+  TDriver extends IdentityDriver<IdentityCapabilities, unknown, infer TActor, unknown>
+    ? TActor
+    : never
+
+type MfaIdentityFor<TCapabilities extends IdentityCapabilities> = [
+  CapabilityMembers<TCapabilities['mfa']>,
+] extends [never]
+  ? object
+  : MfaIdentitySurface<CapabilityMembers<TCapabilities['mfa']>>
+
+/** Identity facade narrowed to the exact capabilities of its configured driver. */
+export type Identity<TDriver extends IdentityDriver> = Pick<
+  TDriver,
+  'name' | 'instance' | 'capabilities' | 'user' | 'session' | 'signOut' | 'raw'
+> &
+  CapabilitySurface<
+    TDriver['capabilities']['passwords'],
+    PasswordIdentitySurface<ActorOf<TDriver>>
+  > &
+  CapabilitySurface<TDriver['capabilities']['magicLinks'], MagicLinkIdentitySurface> &
+  CapabilitySurface<TDriver['capabilities']['oauth'], OAuthIdentitySurface> &
+  CapabilitySurface<TDriver['capabilities']['organizations'], OrganizationIdentitySurface> &
+  MfaIdentityFor<TDriver['capabilities']>
+
+/** Authentication facade alias matching the application-facing `Auth` vocabulary. */
+export type Auth<TDriver extends IdentityDriver> = Identity<TDriver>

package/src/drivers/logs.ts

@@ -0,0 +1,61 @@
+import type { CapabilitySurface, DriverContract } from './common'
+
+/** Literal structured logging capabilities. */
+export interface LogCapabilities {
+  /** Whether distributed traces and spans are available. */
+  readonly traces: boolean
+}
+
+/** Portable structured log severity. */
+export type LogLevel = 'debug' | 'info' | 'warning' | 'error'
+
+/** Structured log record emitted by application code. */
+export interface LogRecord {
+  /** Severity used for filtering and alerting. */
+  level: LogLevel
+  /** Human-readable event message. */
+  message: string
+  /** Framework-owned structured context. */
+  context?: Readonly<Record<string, unknown>>
+  /** Event time, defaulting to the current time when omitted. */
+  timestamp?: Date
+}
+
+/** Active trace span returned by a tracing-capable driver. */
+export interface TraceSpan {
+  /** Stable trace identifier. */
+  readonly traceId: string
+  /** Stable span identifier. */
+  readonly spanId: string
+  /** Adds a structured attribute to the span. */
+  attribute(name: string, value: string | number | boolean): void
+  /** Records an error without exposing a vendor event shape. */
+  recordError(error: unknown): void
+  /** Finishes the span. */
+  end(): void
+}
+
+/** Base structured logging contract. */
+export interface LogDriver<
+  TCapabilities extends LogCapabilities = LogCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Writes one structured log record. */
+  write(record: LogRecord): Promise<void>
+}
+
+/** Trace methods exposed only by tracing-capable log drivers. */
+export interface TraceLogSurface {
+  /** Starts a named trace span with optional structured attributes. */
+  startSpan(
+    name: string,
+    attributes?: Readonly<Record<string, string | number | boolean>>,
+  ): TraceSpan
+}
+
+/** Logging facade narrowed to its driver's tracing capability. */
+export type Logs<TDriver extends LogDriver> = Pick<
+  TDriver,
+  'name' | 'instance' | 'capabilities' | 'write' | 'raw'
+> &
+  CapabilitySurface<TDriver['capabilities']['traces'], TraceLogSurface>

package/src/drivers/mail.ts

@@ -0,0 +1,73 @@
+import type { CapabilitySurface, DriverContract } from './common'
+
+/** Literal mail features used to narrow delivery methods. */
+export interface MailCapabilities {
+  /** Whether provider-hosted templates may be sent. */
+  readonly templates: boolean
+}
+
+/** Portable attachment included with a mail message. */
+export interface MailAttachment {
+  /** Attachment filename presented to the recipient. */
+  filename: string
+  /** Attachment bytes. */
+  content: Uint8Array
+  /** Media type when known. */
+  contentType?: string
+}
+
+/** Transport-neutral transactional email message. */
+export interface MailMessage {
+  /** Recipient addresses. */
+  to: string | readonly string[]
+  /** Sender address, or the configured instance default when omitted. */
+  from?: string
+  /** Address or addresses that receive recipient replies. */
+  replyTo?: string | readonly string[]
+  /** Carbon-copy recipient addresses. */
+  cc?: readonly string[]
+  /** Blind-carbon-copy recipient addresses. */
+  bcc?: readonly string[]
+  /** Message subject. */
+  subject: string
+  /** Plain-text message body. */
+  text?: string
+  /** HTML message body. */
+  html?: string
+  /** File attachments. */
+  attachments?: readonly MailAttachment[]
+}
+
+/** Result of accepting a message for delivery. */
+export interface MailReceipt {
+  /** Stable message identifier. */
+  id: string
+  /** Recipient addresses accepted by the driver. */
+  accepted: readonly string[]
+}
+
+/** Base transactional mail contract. */
+export interface MailDriver<
+  TCapabilities extends MailCapabilities = MailCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Sends one transport-neutral transactional message. */
+  send(message: MailMessage): Promise<MailReceipt>
+}
+
+/** Hosted-template delivery exposed only by template-capable mail drivers. */
+export interface TemplateMailSurface {
+  /** Sends a provider-hosted template with serializable variables. */
+  sendTemplate(
+    template: string,
+    to: string | readonly string[],
+    variables: Readonly<Record<string, unknown>>,
+  ): Promise<MailReceipt>
+}
+
+/** Mail facade narrowed to its driver's template capability. */
+export type Mail<TDriver extends MailDriver> = Pick<
+  TDriver,
+  'name' | 'instance' | 'capabilities' | 'send' | 'raw'
+> &
+  CapabilitySurface<TDriver['capabilities']['templates'], TemplateMailSurface>

package/src/drivers/notifications.ts

@@ -0,0 +1,64 @@
+import type { CapabilityMembers, DriverContract } from './common'
+
+/** Portable notification delivery channels. */
+export type NotificationChannel = 'push' | 'sms' | 'inApp'
+
+/** Literal notification channels supported by a driver instance. */
+export interface NotificationCapabilities<
+  TChannel extends NotificationChannel = NotificationChannel,
+> {
+  /** Delivery channels retained as a literal readonly list. */
+  readonly channels: readonly TChannel[]
+}
+
+/** Transport-neutral notification request. */
+export interface NotificationMessage<TData = unknown> {
+  /** Framework actor or destination identifier. */
+  recipient: string
+  /** Notification title when the channel presents one. */
+  title?: string
+  /** Human-readable notification body. */
+  body: string
+  /** Serializable channel-specific application data. */
+  data?: TData
+}
+
+/** Result of accepting a notification for delivery. */
+export interface NotificationReceipt {
+  /** Stable delivery identifier. */
+  id: string
+  /** Channel used for delivery. */
+  channel: NotificationChannel
+}
+
+/** Push, SMS, and in-app notification contract. */
+export interface NotificationDriver<
+  TCapabilities extends NotificationCapabilities = NotificationCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Sends a message through a notification channel. */
+  send<TData>(
+    channel: NotificationChannel,
+    message: NotificationMessage<TData>,
+  ): Promise<NotificationReceipt>
+}
+
+/** Notification facade restricted to its driver's literal channel list. */
+export interface NotificationSurface<TDriver extends NotificationDriver> {
+  /** Driver implementation name. */
+  readonly name: TDriver['name']
+  /** Configured notification connection name. */
+  readonly instance: TDriver['instance']
+  /** Exact notification channel declaration. */
+  readonly capabilities: TDriver['capabilities']
+  /** Sends a notification through a configured channel. */
+  send<TData>(
+    channel: CapabilityMembers<TDriver['capabilities']['channels']>,
+    message: NotificationMessage<TData>,
+  ): Promise<NotificationReceipt>
+  /** Returns the driver's typed underlying client. */
+  raw(): ReturnType<TDriver['raw']>
+}
+
+/** Notification facade narrowed to configured channel literals. */
+export type Notifications<TDriver extends NotificationDriver> = NotificationSurface<TDriver>

package/src/drivers/payments.ts

@@ -0,0 +1,107 @@
+import type { CapabilitySurface, DriverContract } from './common'
+
+/** Literal payment features used to narrow commerce operations. */
+export interface PaymentCapabilities {
+  /** Whether recurring subscriptions are available. */
+  readonly subscriptions: boolean
+  /** Whether hosted checkout sessions are available. */
+  readonly checkout: boolean
+  /** Whether signed webhook events can be normalized. */
+  readonly webhooks: boolean
+}
+
+/** Framework-neutral payment customer. */
+export interface PaymentCustomer {
+  /** Stable customer identifier. */
+  id: string
+  /** Customer email when known. */
+  email?: string
+  /** Application metadata attached to the customer. */
+  metadata: Readonly<Record<string, string>>
+}
+
+/** Framework-neutral recurring subscription. */
+export interface PaymentSubscription {
+  /** Stable subscription identifier. */
+  id: string
+  /** Stable customer identifier. */
+  customerId: string
+  /** Application price or plan identifier. */
+  priceId: string
+  /** Normalized lifecycle status. */
+  status: 'trialing' | 'active' | 'past_due' | 'canceled' | 'paused'
+  /** End of the current billing period when known. */
+  currentPeriodEndsAt?: Date
+}
+
+/** Hosted checkout session created by a payment driver. */
+export interface CheckoutSession {
+  /** Stable checkout session identifier. */
+  id: string
+  /** URL where the actor completes checkout. */
+  url: string
+  /** Time after which the checkout URL is invalid. */
+  expiresAt?: Date
+}
+
+/** Normalized payment webhook event. */
+export interface PaymentWebhook<TData = unknown> {
+  /** Stable event identifier used for idempotency. */
+  id: string
+  /** Framework-neutral event name. */
+  type: string
+  /** Normalized event data. */
+  data: TData
+  /** Time the payment system created the event. */
+  occurredAt: Date
+}
+
+/** Base customer operations provided by every payment driver. */
+export interface PaymentDriver<
+  TCapabilities extends PaymentCapabilities = PaymentCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Creates a payment customer. */
+  createCustomer(input: {
+    readonly email?: string
+    readonly metadata?: Readonly<Record<string, string>>
+  }): Promise<PaymentCustomer>
+  /** Retrieves a payment customer. */
+  customer(id: string): Promise<PaymentCustomer>
+}
+
+/** Subscription methods exposed only by subscription-capable payment drivers. */
+export interface SubscriptionPaymentSurface {
+  /** Creates a recurring subscription for a customer and price. */
+  subscribe(customerId: string, priceId: string): Promise<PaymentSubscription>
+  /** Retrieves a recurring subscription. */
+  subscription(id: string): Promise<PaymentSubscription>
+  /** Cancels a recurring subscription. */
+  cancelSubscription(id: string): Promise<PaymentSubscription>
+}
+
+/** Checkout methods exposed only by checkout-capable payment drivers. */
+export interface CheckoutPaymentSurface {
+  /** Creates a hosted checkout session. */
+  checkout(input: {
+    readonly customerId?: string
+    readonly priceId: string
+    readonly successUrl: string
+    readonly cancelUrl: string
+  }): Promise<CheckoutSession>
+}
+
+/** Webhook methods exposed only by webhook-capable payment drivers. */
+export interface WebhookPaymentSurface {
+  /** Verifies and normalizes a raw webhook request. */
+  webhook(payload: Uint8Array, signature: string): Promise<PaymentWebhook>
+}
+
+/** Payments facade narrowed to subscriptions, checkout, and webhook capabilities. */
+export type Payments<TDriver extends PaymentDriver> = Pick<
+  TDriver,
+  'name' | 'instance' | 'capabilities' | 'createCustomer' | 'customer' | 'raw'
+> &
+  CapabilitySurface<TDriver['capabilities']['subscriptions'], SubscriptionPaymentSurface> &
+  CapabilitySurface<TDriver['capabilities']['checkout'], CheckoutPaymentSurface> &
+  CapabilitySurface<TDriver['capabilities']['webhooks'], WebhookPaymentSurface>

package/src/drivers/queue.ts

@@ -0,0 +1,87 @@
+import type { CapabilitySurface, DriverContract } from './common'
+
+/** Literal durable queue features used to narrow queue operations. */
+export interface QueueCapabilities {
+  /** Whether jobs may be scheduled for later delivery. */
+  readonly delayed: boolean
+  /** Whether failed jobs may be retried. */
+  readonly retries: boolean
+  /** Whether terminal failures are retained for inspection and replay. */
+  readonly deadLetter: boolean
+}
+
+/** Serializable job submitted to a queue driver. */
+export interface QueueJob<TPayload = unknown> {
+  /** Registered job name. */
+  name: string
+  /** Serializable job payload. */
+  payload: TPayload
+  /** Named destination queue. */
+  queue?: string
+}
+
+/** Delivery metadata supplied while draining a queue. */
+export interface QueueReceipt<TPayload = unknown> {
+  /** Stable queued-job identifier. */
+  id: string
+  /** Deserialized job. */
+  job: QueueJob<TPayload>
+  /** One-based execution attempt. */
+  attempt: number
+}
+
+/** Failed job retained by a dead-letter-capable driver. */
+export interface FailedQueueJob extends QueueReceipt {
+  /** Framework-normalized failure message. */
+  error: string
+  /** Time the terminal failure was recorded. */
+  failedAt: Date
+}
+
+/** Base enqueue and drain contract. */
+export interface QueueDriver<
+  TCapabilities extends QueueCapabilities = QueueCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Enqueues a job for immediate delivery and returns its identifier. */
+  enqueue<TPayload>(job: QueueJob<TPayload>): Promise<string>
+  /**
+   * Drains available jobs. Handler resolution removes a job; a thrown error releases it for
+   * redelivery with `attempt` incremented, subject to the `retries` and `deadLetter` capabilities.
+   */
+  drain(
+    handler: (receipt: QueueReceipt) => Promise<void>,
+    options?: { readonly queue?: string; readonly limit?: number },
+  ): Promise<number>
+}
+
+/** Delayed delivery exposed only by drivers that support scheduling. */
+export interface DelayedQueueSurface {
+  /** Enqueues a job no earlier than the requested time. */
+  enqueueAt<TPayload>(job: QueueJob<TPayload>, availableAt: Date): Promise<string>
+}
+
+/** Retry operations exposed only by retry-capable queue drivers. */
+export interface RetryQueueSurface {
+  /** Releases a failed attempt using an optional delay. */
+  retry(id: string, delaySeconds?: number): Promise<void>
+}
+
+/** Dead-letter operations exposed only when terminal failures are retained. */
+export interface DeadLetterQueueSurface {
+  /** Lists retained terminal failures. */
+  failed(queue?: string): Promise<readonly FailedQueueJob[]>
+  /** Replays a retained terminal failure. */
+  replay(id: string): Promise<void>
+  /** Permanently removes a retained terminal failure. */
+  forget(id: string): Promise<void>
+}
+
+/** Queue facade narrowed to delayed, retry, and dead-letter capabilities. */
+export type Queue<TDriver extends QueueDriver> = Pick<
+  TDriver,
+  'name' | 'instance' | 'capabilities' | 'enqueue' | 'drain' | 'raw'
+> &
+  CapabilitySurface<TDriver['capabilities']['delayed'], DelayedQueueSurface> &
+  CapabilitySurface<TDriver['capabilities']['retries'], RetryQueueSurface> &
+  CapabilitySurface<TDriver['capabilities']['deadLetter'], DeadLetterQueueSurface>

package/src/drivers/ratelimit.ts

@@ -0,0 +1,66 @@
+import type { CapabilityMembers, DriverContract } from './common'
+
+/** Portable rate-limit algorithms. */
+export type RateLimitAlgorithm = 'tokenBucket' | 'slidingWindow'
+
+/** Literal rate-limit algorithms supported by a driver instance. */
+export interface RateLimitCapabilities<TAlgorithm extends RateLimitAlgorithm = RateLimitAlgorithm> {
+  /** Algorithms retained as a literal readonly list. */
+  readonly algorithms: readonly TAlgorithm[]
+}
+
+/** Portable rate-limit policy. */
+export interface RateLimitPolicy<TAlgorithm extends RateLimitAlgorithm = RateLimitAlgorithm> {
+  /** Algorithm used to evaluate the key. */
+  algorithm: TAlgorithm
+  /** Maximum accepted operations in the configured window or bucket. */
+  limit: number
+  /** Window or refill duration in seconds. */
+  intervalSeconds: number
+}
+
+/** Result of consuming capacity from a rate limit. */
+export interface RateLimitDecision {
+  /** Whether the operation may proceed. */
+  allowed: boolean
+  /** Capacity remaining after this decision. */
+  remaining: number
+  /** Epoch time in milliseconds when full capacity resets. */
+  resetsAt: number
+  /** Milliseconds until retry when the operation was denied. */
+  retryAfterMs?: number
+}
+
+/** Token-bucket and sliding-window rate-limit contract. */
+export interface RateLimitDriver<
+  TCapabilities extends RateLimitCapabilities = RateLimitCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Consumes capacity for a key under the supplied policy. */
+  consume(key: string, policy: RateLimitPolicy, cost?: number): Promise<RateLimitDecision>
+  /** Clears accumulated state for a key. */
+  reset(key: string): Promise<void>
+}
+
+/** Rate-limit facade restricted to its driver's literal algorithm list. */
+export interface RateLimitSurface<TDriver extends RateLimitDriver> {
+  /** Driver implementation name. */
+  readonly name: TDriver['name']
+  /** Configured limiter name. */
+  readonly instance: TDriver['instance']
+  /** Exact algorithm capability declaration. */
+  readonly capabilities: TDriver['capabilities']
+  /** Consumes capacity using one configured algorithm. */
+  consume(
+    key: string,
+    policy: RateLimitPolicy<CapabilityMembers<TDriver['capabilities']['algorithms']>>,
+    cost?: number,
+  ): Promise<RateLimitDecision>
+  /** Clears accumulated state for a key. */
+  reset(key: string): Promise<void>
+  /** Returns the driver's typed underlying client. */
+  raw(): ReturnType<TDriver['raw']>
+}
+
+/** Rate-limit facade narrowed to configured algorithm literals. */
+export type RateLimit<TDriver extends RateLimitDriver> = RateLimitSurface<TDriver>

package/src/drivers/realtime.ts

@@ -0,0 +1,63 @@
+import type { CapabilitySurface, DriverContract } from './common'
+
+/** Literal realtime features used to narrow channel operations. */
+export interface RealtimeCapabilities {
+  /** Whether channels expose member presence. */
+  readonly presence: boolean
+  /** Whether application messages may be broadcast. */
+  readonly broadcast: boolean
+}
+
+/** Message delivered through a realtime channel. */
+export interface RealtimeMessage<TPayload = unknown> {
+  /** Channel event name. */
+  event: string
+  /** Serializable message payload. */
+  payload: TPayload
+  /** Channel that delivered the message. */
+  channel: string
+}
+
+/** Active realtime subscription. */
+export interface RealtimeSubscription {
+  /** Channel name. */
+  readonly channel: string
+  /** Stops delivery and releases the subscription. */
+  unsubscribe(): Promise<void>
+}
+
+/** Base realtime channel subscription contract. */
+export interface RealtimeDriver<
+  TCapabilities extends RealtimeCapabilities = RealtimeCapabilities,
+  TRaw = unknown,
+> extends DriverContract<TCapabilities, TRaw> {
+  /** Subscribes to messages on a named channel. */
+  subscribe<TPayload = unknown>(
+    channel: string,
+    handler: (message: RealtimeMessage<TPayload>) => void | Promise<void>,
+  ): Promise<RealtimeSubscription>
+}
+
+/** Presence operations exposed only by presence-capable realtime drivers. */
+export interface PresenceRealtimeSurface {
+  /** Joins channel presence with explicit serializable member state. */
+  joinPresence(channel: string, member: Readonly<Record<string, unknown>>): Promise<void>
+  /** Leaves channel presence. */
+  leavePresence(channel: string): Promise<void>
+  /** Lists current channel members. */
+  presence(channel: string): Promise<readonly Readonly<Record<string, unknown>>[]>
+}
+
+/** Broadcast operations exposed only by broadcast-capable realtime drivers. */
+export interface BroadcastRealtimeSurface {
+  /** Broadcasts a serializable event to a channel. */
+  broadcast<TPayload>(channel: string, event: string, payload: TPayload): Promise<void>
+}
+
+/** Realtime facade narrowed to presence and broadcast capabilities. */
+export type Realtime<TDriver extends RealtimeDriver> = Pick<
+  TDriver,
+  'name' | 'instance' | 'capabilities' | 'subscribe' | 'raw'
+> &
+  CapabilitySurface<TDriver['capabilities']['presence'], PresenceRealtimeSurface> &
+  CapabilitySurface<TDriver['capabilities']['broadcast'], BroadcastRealtimeSurface>