@nymbalhq/platform 0.2.0 → 1.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { NymbalConfig } from '@nymbalhq/config';
-import { Logger, DocumentStoreAdapter, EventBusAdapter, Product, ProductStatus, ProductType, ProductMedia, Variant, VariantDimensions, VariantOption, VariantStatus, Category, Customer, Role, CustomerAddress, Order, OrderStatus, Address, OrderLineItem, CaptureMethod, OrderHistoryEntry, OrderRefundStatus, OrderRefund, InventoryReservation, StockAdjustmentReason, StockAdjustment, Review, ReviewModerationStatus, NymbalEvent, Cart, PutOptions, QueryParams, QueryResult, EventHandler, SubscriptionConfig, Subscription, NymbalEnvironment, NymbalEventType, NymbalEventMap, SecurityAdapter, PaymentsAdapter, EmailAdapter, SearchAdapter, ReviewsAdapter, AnalyticsAdapter, ShippingAdapter, TaxAdapter, AiAdapter, ProductSnapshot, CartItem, StockStatus, PaymentIntent, CheckoutPayment, SearchParams, SearchResult, OrderPayment, Refund, HttpAdapter, RateLimitAction, SecurityConfigLike } from '@nymbalhq/types';
+import { Logger, DocumentStoreAdapter, EventBusAdapter, Product, ProductStatus, ProductType, ProductMedia, Variant, VariantDimensions, VariantOption, VariantStatus, Category, Customer, Role, CustomerAddress, Order, OrderStatus, Address, OrderLineItem, CaptureMethod, OrderHistoryEntry, OrderRefundStatus, OrderRefund, InventoryReservation, StockAdjustmentReason, StockAdjustment, Review, ReviewModerationStatus, NymbalEvent, Cart, PutOptions, QueryParams, QueryResult, EventHandler, SubscriptionConfig, Subscription, NymbalEnvironment, NymbalEventType, NymbalEventMap, PaymentsAdapter, EmailAdapter, ReviewsAdapter, SearchAdapter, AnalyticsAdapter, ShippingAdapter, TaxAdapter, AiAdapter, SecurityAdapter, ProductSnapshot, CartItem, StockStatus, PaymentIntent, CheckoutPayment, SearchParams, SearchResult, OrderPayment, Refund, HttpAdapter, CommerceSlot, RateLimitAction, SecurityConfigLike } from '@nymbalhq/types';
 import BetterSqlite3 from 'better-sqlite3';
 import pg from 'pg';
 import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
@@ -597,6 +597,7 @@ interface InMemoryDocumentStoreOptions {
 declare class InMemoryDocumentStore implements DocumentStoreAdapter {
     #private;
     constructor(options?: InMemoryDocumentStoreOptions);
+    capabilities(): readonly string[];
     get<T>(collection: string, key: string): Promise<T | null>;
     put<T>(collection: string, key: string, document: T, options?: PutOptions): Promise<void>;
     delete(collection: string, key: string): Promise<void>;
@@ -614,6 +615,7 @@ interface InProcessEventBusOptions {
 declare class InProcessEventBus implements EventBusAdapter {
     #private;
     constructor(options?: InProcessEventBusOptions);
+    capabilities(): readonly string[];
     publish<T>(event: NymbalEvent<T>): Promise<void>;
     publishBatch(events: NymbalEvent<unknown>[]): Promise<void>;
     replay(events: NymbalEvent<unknown>[]): Promise<void>;
@@ -688,28 +690,33 @@ interface IdempotencyOptions {
 }
 declare function withIdempotency<T = unknown>(handlerName: string, handler: EventHandler<T>, { repo, logger }: IdempotencyOptions): EventHandler<T>;
 
-interface AdapterRegistry {
-    security: SecurityAdapter;
+/** One adapter per commerce slot. */
+interface CommerceAdapters {
     payments: PaymentsAdapter;
     email: EmailAdapter;
-    search: SearchAdapter;
     reviews: ReviewsAdapter;
+    search: SearchAdapter;
     analytics: AnalyticsAdapter;
     shipping: ShippingAdapter;
     tax: TaxAdapter;
     ai: AiAdapter;
 }
+/** Adapters a project hands `createApp`, each for a slot whose provider is `custom`. */
+type InjectedAdapters = Partial<CommerceAdapters>;
+interface AdapterRegistry extends Omit<CommerceAdapters, 'ai'> {
+    security: SecurityAdapter;
+    /** `null` when the config's ai provider is `none`. */
+    ai: AiAdapter | null;
+}
 interface BuildAdaptersDeps {
     config: NymbalConfig;
     logger: Logger;
     documentStore: DocumentStoreAdapter;
     repos: Repositories;
+    injected?: InjectedAdapters;
+    /** The payments adapter `createApp` resolved before it opened the store. */
+    payments: PaymentsAdapter;
 }
-/**
- * The `providerName` of the payments adapter a configured provider resolves to. A provider with no adapter of its
- * own falls back to the stub, which verifies no webhook signature.
- */
-declare function paymentsAdapterFor(provider: string): 'stripe' | 'native-stub';
 declare function buildAdapters(deps: BuildAdaptersDeps): Promise<AdapterRegistry>;
 
 interface RegisterHandlersDeps {
@@ -1143,13 +1150,23 @@ interface NymbalApp {
      * or null for a 404 that says how to build it) or `NYMBAL_ADMIN_DIST` is set.
      */
     attachHttp(adapter: HttpAdapter, options?: AttachHttpOptions): Promise<void>;
+    /** Each slot's provider and its adapter's own `capabilities()`; an ai slot of `none` offers nothing. */
+    capabilities(): CapabilitiesReport;
     stop(): Promise<void>;
 }
+type CapabilitySlot = CommerceSlot | 'security' | 'documentStore' | 'eventBus' | 'media';
+interface SlotCapabilities {
+    provider: string;
+    capabilities: readonly string[];
+}
+type CapabilitiesReport = Record<CapabilitySlot, SlotCapabilities>;
 interface AttachHttpOptions {
     adminRoot?: string | null;
 }
 interface CreateAppOptions extends CreatePlatformOptions {
     version?: string;
+    /** The project's own adapters, one per slot whose provider is `custom`. */
+    adapters?: InjectedAdapters;
 }
 declare function createApp(config: NymbalConfig, options?: CreateAppOptions): Promise<NymbalApp>;
 
@@ -1202,6 +1219,18 @@ interface EventRetentionSweeperDeps {
 /** Deletes delivered events and processed-event records older than the window; undelivered and dead events stay. */
 declare function startEventRetentionSweeper(deps: EventRetentionSweeperDeps): SweeperHandle;
 
+interface ProviderPackage {
+    /** The adapter package, which exports `createAdapter(ctx: AdapterContext)`. */
+    package: string;
+    /** The provider SDK the package peers, which the project installs beside it. */
+    sdk: string;
+}
+/**
+ * The providers that live in their own package, by slot then provider. The kernel imports a package only when the
+ * config names its provider; `native`, `none` and `custom` have no entry.
+ */
+declare const PROVIDER_PACKAGES: Readonly<Partial<Record<CommerceSlot, Readonly<Record<string, ProviderPackage>>>>>;
+
 /**
  * v0.1 security adapter.
  *
@@ -1234,22 +1263,6 @@ declare function buildSecurityHeaders(security: SecurityConfigLike): Record<stri
 declare const CSRF_COOKIE = "nymbal.csrf";
 declare const CSRF_HEADER = "x-csrf-token";
 
-interface StripePaymentsConfig {
-    secretKey: string;
-    webhookSecret: string;
-    apiVersion?: string;
-    /** Override the Stripe API host (for stripe-mock style test servers). Omit in production. */
-    host?: string;
-    /** Override the Stripe API port. Only used together with `host`. */
-    port?: number;
-    /** Override the Stripe API protocol. Defaults to https when omitted. */
-    protocol?: 'http' | 'https';
-}
-declare function createStripePaymentsAdapter(deps: {
-    logger: Logger;
-    config: StripePaymentsConfig;
-}): PaymentsAdapter;
-
 /**
  * Deterministic payments adapter for local development without Stripe keys.
  * Every intent succeeds at creation unless the receipt email asks otherwise (`statusFor`); webhook verification is a
@@ -1260,16 +1273,10 @@ declare function createNativeStubPaymentsAdapter(deps: {
     logger: Logger;
 }): PaymentsAdapter;
 
+/** The native provider logs mail to the console; SMTP is the `smtp` provider (@nymbalhq/adapter-smtp). */
 interface NativeEmailAdapterConfig {
-    transport?: 'console' | 'smtp';
+    transport?: 'console';
     from?: string;
-    smtp?: {
-        host: string;
-        port: number;
-        user?: string;
-        pass?: string;
-        secure?: boolean;
-    };
 }
 declare function createNativeEmailAdapter(deps: {
     logger: Logger;
@@ -1294,13 +1301,6 @@ declare function createNativeTaxAdapter(logger: Logger, defaultRate?: number): T
 
 declare function createNativeAiAdapter(_logger: Logger): AiAdapter;
 
-interface AnthropicAiAdapterConfig {
-    apiKey: string;
-    model?: string;
-    logger: Logger;
-}
-declare function createAnthropicAiAdapter(config: AnthropicAiAdapterConfig): AiAdapter;
-
 interface CreateLoggerOptions {
     level?: string;
     pretty?: boolean;
@@ -1358,6 +1358,7 @@ declare const seedCategories: SeedCategory[];
 declare const seedProducts: SeedProduct[];
 
 interface MediaStorage {
+    capabilities(): readonly string[];
     put(key: string, body: Uint8Array, contentType: string): Promise<{
         url: string;
     }>;
@@ -1369,4 +1370,4 @@ interface LocalFsMediaStorageOptions {
 }
 declare function createLocalFsMediaStorage(options: LocalFsMediaStorageOptions): MediaStorage;
 
-export { type AbandonedCart, type AbandonedWindow, type AdapterRegistry, type AnthropicAiAdapterConfig, type AttachHttpOptions, type AuthService, type AuthTokens, type BeginCheckoutInput, type BeginCheckoutResult, type BuildAdaptersDeps, type BuildServicesDeps, CSRF_COOKIE, CSRF_HEADER, type CapturedPayment, type CartRepository, type CartService, type CategoryCreateInput, type CategoryInsert, type CategoryRepository, type CategoryService, type CategoryUpdate, type CategoryUpdateInput, type CheckoutService, type CommandStore, type CreateAppOptions, type CreateAuthServiceDeps, type CreateCartServiceDeps, type CreateCheckoutServiceDeps, type CreateInventoryServiceDeps, type CreateLoggerOptions, type CreateOrderServiceDeps, type CreatePlatformOptions, type CreateProductServiceDeps, type CreatePublisherOptions, type CreateRefundServiceDeps, type CreateRelayOptions, type CustomerInsert, type CustomerJwtPayload, type CustomerRepository, type CustomerService, type CustomerUpdate, type CustomerWithHash, type EventBuilderContext, type EventLogRepository, type EventPublisher, type EventRetentionSweeperDeps, type FinalizeResult, type IdempotencyOptions, type ImportCustomerInput, InMemoryDocumentStore, type InMemoryDocumentStoreOptions, InProcessEventBus, type InProcessEventBusOptions, type InventoryReservationRepository, type InventoryService, type CategoryInsert$1 as LegacyCategoryInsert, type CategoryRow as LegacyCategoryRow, type ProductInsert$1 as LegacyProductInsert, type ProductRow as LegacyProductRow, type LocalFsMediaStorageOptions, type LoggedEvent, type MakeEventOptions, type ManualPayments, type MediaStorage, type MigrateOptions, type NativeEmailAdapterConfig, type NymbalApp, type OrderCapture, type OrderCreateDraftInput, type OrderHistoryInsert, type OrderHistoryRepository, type OrderImportInput, type OrderInsert, type OrderRefundInsert, type OrderRefundRepository, type OrderRepository, type OrderSequenceRepository, type OrderService, PROVIDER_REFUND_REASON, type Platform, type PostgresClient, type ProcessedEventRepository, type ProductCategoryRepository, type ProductCreateInput, type ProductInsert, type ProductRepository, type ProductService, type ProductUpdate, type ProductUpdateInput, type ProfileUpdate, type PublishOptions, RateLimiter, type RawClients, type ReadTx, type RefreshTokenInsert, type RefreshTokenRepository, type RefreshTokenRow, type RefundInput, type RefundResult, type RefundService, type RegisterAllRoutesDeps, type RegisterHandlersDeps, type RegisterInput, type Relay, type Repositories, type ReservationInsert, type ReserveStockResult, type ReviewInsert, type ReviewRepository, type RouteSchema, type SearchService, type SeedCategory, type SeedDeps, type SeedProduct, type SeedResult, type ServiceRegistry, type Settlement, type SqliteClient, type StockAdjustmentInsert, type StockAdjustmentRepository, type StoreRepository, type StripePaymentsConfig, type SweeperHandle, type Tx, type VariantInsert, type VariantRepository, type VariantUpdate, type WarmDocumentStoreDeps, type WarmResult, buildAdapters, buildRepositories, buildSecurityHeaders, buildServices, createAnthropicAiAdapter, createApp, createAuthService, createCartRepository, createCartService, createCategoryRepository, createCategoryService, createCheckoutService, createCommandStore, createCustomerRepository, createCustomerService, createDocumentStore, createEventBuilder, createEventBus, createEventLogRepository, createEventPublisher, createInventoryReservationRepository, createInventoryService, createCategoryRepository$1 as createLegacyCategoryRepository, createProductRepository$1 as createLegacyProductRepository, createLocalFsMediaStorage, createLogger, createMiddlewareSecurityAdapter, createNativeAiAdapter, createNativeAnalyticsAdapter, createNativeEmailAdapter, createNativeReviewsAdapter, createNativeSearchAdapter, createNativeShippingAdapter, createNativeStubPaymentsAdapter, createNativeTaxAdapter, createOrderHistoryRepository, createOrderRefundRepository, createOrderRepository, createOrderSequenceRepository, createOrderService, createPlatform, createProcessedEventRepository, createProductCategoryRepository, createProductRepository, createProductService, createRefreshTokenRepository, createRefundService, createRelay, createReviewRepository, createSearchService, createStockAdjustmentRepository, createStripePaymentsAdapter, createVariantRepository, orderPayment, paymentsAdapterFor, rawClients, refreshRefunded, registerAdminStaticRoute, registerAllRoutes, registerHandlers, routeSchemas, runMigrations, runSeed, seedCategories, seedProducts, settlementOf, startCartAbandonmentSweeper, startEventRetentionSweeper, startInventoryReservationSweeper, warmDocumentStore, withIdempotency };
+export { type AbandonedCart, type AbandonedWindow, type AdapterRegistry, type AttachHttpOptions, type AuthService, type AuthTokens, type BeginCheckoutInput, type BeginCheckoutResult, type BuildAdaptersDeps, type BuildServicesDeps, CSRF_COOKIE, CSRF_HEADER, type CapabilitiesReport, type CapabilitySlot, type CapturedPayment, type CartRepository, type CartService, type CategoryCreateInput, type CategoryInsert, type CategoryRepository, type CategoryService, type CategoryUpdate, type CategoryUpdateInput, type CheckoutService, type CommandStore, type CommerceAdapters, type CreateAppOptions, type CreateAuthServiceDeps, type CreateCartServiceDeps, type CreateCheckoutServiceDeps, type CreateInventoryServiceDeps, type CreateLoggerOptions, type CreateOrderServiceDeps, type CreatePlatformOptions, type CreateProductServiceDeps, type CreatePublisherOptions, type CreateRefundServiceDeps, type CreateRelayOptions, type CustomerInsert, type CustomerJwtPayload, type CustomerRepository, type CustomerService, type CustomerUpdate, type CustomerWithHash, type EventBuilderContext, type EventLogRepository, type EventPublisher, type EventRetentionSweeperDeps, type FinalizeResult, type IdempotencyOptions, type ImportCustomerInput, InMemoryDocumentStore, type InMemoryDocumentStoreOptions, InProcessEventBus, type InProcessEventBusOptions, type InjectedAdapters, type InventoryReservationRepository, type InventoryService, type CategoryInsert$1 as LegacyCategoryInsert, type CategoryRow as LegacyCategoryRow, type ProductInsert$1 as LegacyProductInsert, type ProductRow as LegacyProductRow, type LocalFsMediaStorageOptions, type LoggedEvent, type MakeEventOptions, type ManualPayments, type MediaStorage, type MigrateOptions, type NativeEmailAdapterConfig, type NymbalApp, type OrderCapture, type OrderCreateDraftInput, type OrderHistoryInsert, type OrderHistoryRepository, type OrderImportInput, type OrderInsert, type OrderRefundInsert, type OrderRefundRepository, type OrderRepository, type OrderSequenceRepository, type OrderService, PROVIDER_PACKAGES, PROVIDER_REFUND_REASON, type Platform, type PostgresClient, type ProcessedEventRepository, type ProductCategoryRepository, type ProductCreateInput, type ProductInsert, type ProductRepository, type ProductService, type ProductUpdate, type ProductUpdateInput, type ProfileUpdate, type ProviderPackage, type PublishOptions, RateLimiter, type RawClients, type ReadTx, type RefreshTokenInsert, type RefreshTokenRepository, type RefreshTokenRow, type RefundInput, type RefundResult, type RefundService, type RegisterAllRoutesDeps, type RegisterHandlersDeps, type RegisterInput, type Relay, type Repositories, type ReservationInsert, type ReserveStockResult, type ReviewInsert, type ReviewRepository, type RouteSchema, type SearchService, type SeedCategory, type SeedDeps, type SeedProduct, type SeedResult, type ServiceRegistry, type Settlement, type SlotCapabilities, type SqliteClient, type StockAdjustmentInsert, type StockAdjustmentRepository, type StoreRepository, type SweeperHandle, type Tx, type VariantInsert, type VariantRepository, type VariantUpdate, type WarmDocumentStoreDeps, type WarmResult, buildAdapters, buildRepositories, buildSecurityHeaders, buildServices, createApp, createAuthService, createCartRepository, createCartService, createCategoryRepository, createCategoryService, createCheckoutService, createCommandStore, createCustomerRepository, createCustomerService, createDocumentStore, createEventBuilder, createEventBus, createEventLogRepository, createEventPublisher, createInventoryReservationRepository, createInventoryService, createCategoryRepository$1 as createLegacyCategoryRepository, createProductRepository$1 as createLegacyProductRepository, createLocalFsMediaStorage, createLogger, createMiddlewareSecurityAdapter, createNativeAiAdapter, createNativeAnalyticsAdapter, createNativeEmailAdapter, createNativeReviewsAdapter, createNativeSearchAdapter, createNativeShippingAdapter, createNativeStubPaymentsAdapter, createNativeTaxAdapter, createOrderHistoryRepository, createOrderRefundRepository, createOrderRepository, createOrderSequenceRepository, createOrderService, createPlatform, createProcessedEventRepository, createProductCategoryRepository, createProductRepository, createProductService, createRefreshTokenRepository, createRefundService, createRelay, createReviewRepository, createSearchService, createStockAdjustmentRepository, createVariantRepository, orderPayment, rawClients, refreshRefunded, registerAdminStaticRoute, registerAllRoutes, registerHandlers, routeSchemas, runMigrations, runSeed, seedCategories, seedProducts, settlementOf, startCartAbandonmentSweeper, startEventRetentionSweeper, startInventoryReservationSweeper, warmDocumentStore, withIdempotency };