@serve.zone/interfaces 6.2.0 → 6.3.0

package/readme.md

@@ -14,14 +14,15 @@ pnpm add @serve.zone/interfaces
 
 ## Public API
 
-The root export exposes four namespaces:
+The root export exposes five namespaces:
 
 ```typescript
-import { data, platform, platformservice, requests } from '@serve.zone/interfaces';
+import { appstore, data, platform, platformservice, requests } from '@serve.zone/interfaces';
 ```
 
 | Namespace | Purpose |
 | --- | --- |
+| `appstore` | App Store catalog, manifest, service requirement, and upgrade contracts. |
 | `data` | Durable platform object shapes such as clusters, services, deployments, images, domains, DNS entries, secrets, users, status, settings, backups, registries, BaseOS metadata, and task executions. |
 | `requests` | TypedRequest contracts for Cloudly and serve.zone control-plane RPC methods. |
 | `platform` | Current platform-service contracts for email, SMS, push notifications, letters, AI, databases, object storage, logging, backups, and SIP. |
@@ -71,6 +72,7 @@ Common data contracts include:
 - `IService`, `IDeployment`, `IImage`, `IRegistryTarget`, and `IExternalRegistry` for workload delivery.
 - `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
 - `ISecretBundle` and `ISecretGroup` for secret ownership and shared secret groups.
+- Mail gateway contracts for domain authorities, address bindings, WorkApp bindings, credentials, spool items, delivery journals, and inbound/outbound message payloads.
 - `IUser`, `IIdentity`, and token-related contracts for authentication context.
 - `ICloudlyConfig`, `ICloudlySettings`, status, server, bare-metal, BaseOS, backup, and task execution interfaces for control-plane state.
 
@@ -99,6 +101,7 @@ interface IExampleRequest {
 Request groups are exported by product area:
 
 - `requests.admin`
+- `requests.appstore`
 - `requests.baremetal`
 - `requests.baseos`
 - `requests.backup`
@@ -109,10 +112,12 @@ Request groups are exported by product area:
 - `requests.dns`
 - `requests.domain`
 - `requests.externalRegistry`
+- `requests.hostedapp`
 - `requests.identity`
 - `requests.image`
 - `requests.inform`
 - `requests.log`
+- `requests.mail`
 - `requests.network`
 - `requests.node`
 - `requests.platform`

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '6.2.0',
+  version: '6.3.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/appstore/types.ts

@@ -1,4 +1,4 @@
-export type TAppStorePlatformRequirement = 'mongodb' | 's3' | 'clickhouse' | 'redis' | 'mariadb';
+export type TAppStorePlatformRequirement = 'mongodb' | 's3' | 'clickhouse' | 'valkey' | 'mariadb';
 export type TAppStoreSourceType = 'inline' | 'repoManifest' | 'dockerImage';
 export type TAppStoreTrackingMode = 'tag' | 'digest';
 export type TAppStoreUpgradeStrategy = 'semver' | 'branch' | 'dockerDigest';

package/ts/data/index.ts

@@ -9,6 +9,7 @@ export * from './event.js';
 export * from './externalregistry.js';
 export * from './hostedapp.js';
 export * from './image.js';
+export * from './mail.js';
 export * from './registry.js';
 export * from './secretbundle.js';
 export * from './secretgroup.js';

package/ts/data/mail.ts

@@ -0,0 +1,354 @@
+export type TMailGatewayClientType = 'onebox' | 'cloudly' | 'custom' | (string & {});
+
+export type TMailAddressPatternType = 'exactAddress' | 'domainWildcard' | 'localPartPattern';
+
+export type TMailInboundTargetType = 'webhook' | 'smtpForward' | 'typedEndpoint' | 'discard' | 'reject';
+
+export type TMailRecipientPolicyMode = 'acceptAll' | 'staticList' | 'cachedResolver' | 'appResolver';
+
+export type TMailCredentialType = 'smtp' | 'api';
+
+export type TMailCredentialStatus = 'active' | 'disabled' | 'rotated' | 'revoked';
+
+export type TMailResourceStatus = 'active' | 'disabled' | 'pending' | 'failed';
+
+export type TMailSpoolDirection = 'inbound' | 'outbound';
+
+export type TMailSpoolStatus =
+  | 'accepted'
+  | 'queued'
+  | 'delivering'
+  | 'delivered'
+  | 'deferred'
+  | 'failed'
+  | 'deadLettered'
+  | 'rejected';
+
+export type TMailDeliveryTargetType =
+  | 'webhook'
+  | 'smtpForward'
+  | 'typedEndpoint'
+  | 'mtaRelay'
+  | 'discard'
+  | 'reject';
+
+export type TMailBounceType = 'hard' | 'soft' | 'complaint' | 'unknown';
+
+export type TMailInboundProtocol = 'smtp' | 'submission' | 'api';
+
+export type TMailRecipientResolutionAction = 'accept' | 'reject' | 'defer';
+
+export type TMailDeliveryJournalEventType =
+  | 'accepted'
+  | 'queued'
+  | 'deliveryStarted'
+  | 'deliverySucceeded'
+  | 'deliveryDeferred'
+  | 'deliveryFailed'
+  | 'deadLettered'
+  | 'rejected'
+  | 'bounced'
+  | 'complaint';
+
+/**
+ * Runtime owner of a mail resource. `appInstanceId` is the deployed WorkApp or service
+ * instance, not an App Store template id.
+ */
+export interface IMailResourceOwner {
+  gatewayClientType: TMailGatewayClientType;
+  gatewayClientId: string;
+  appInstanceId?: string;
+}
+
+export interface IMailAddressPattern {
+  type: TMailAddressPatternType;
+  domain: string;
+  localPart?: string;
+  localPartPattern?: string;
+}
+
+export interface IMailWebhookTarget {
+  url: string;
+  signingSecretRef?: string;
+  timeoutMs?: number;
+  headers?: Record<string, string>;
+  maxInlineBytes?: number;
+}
+
+export interface IMailSmtpForwardTarget {
+  host: string;
+  port: number;
+  credentialRef?: string;
+  preserveHeaders?: boolean;
+  addHeaders?: Record<string, string>;
+}
+
+export interface IMailTypedEndpointTarget {
+  serviceRef?: string;
+  method: string;
+  queueName?: string;
+  timeoutMs?: number;
+}
+
+export interface IMailInboundTarget {
+  type: TMailInboundTargetType;
+  webhook?: IMailWebhookTarget;
+  smtpForward?: IMailSmtpForwardTarget;
+  typedEndpoint?: IMailTypedEndpointTarget;
+  reject?: {
+    smtpCode: number;
+    message: string;
+  };
+}
+
+export interface IMailRecipientResolverTarget {
+  type: 'webhook' | 'typedEndpoint';
+  webhook?: IMailWebhookTarget;
+  typedEndpoint?: IMailTypedEndpointTarget;
+}
+
+export interface IMailRecipientPolicy {
+  mode: TMailRecipientPolicyMode;
+  staticRecipients?: string[];
+  resolver?: IMailRecipientResolverTarget;
+  cacheTtlMs?: number;
+  unavailableResponse?: {
+    smtpCode: number;
+    message: string;
+  };
+}
+
+export interface IMailSpoolPolicy {
+  enabled: boolean;
+  maxRetryAgeMs?: number;
+  retentionMs?: number;
+  maxQueuedMessages?: number;
+  maxQueuedBytes?: number;
+  initialRetryDelayMs?: number;
+  maxRetryDelayMs?: number;
+  deadLetterOnExpiry?: boolean;
+}
+
+export interface IMailRateLimits {
+  messagesPerMinute?: number;
+  messagesPerHour?: number;
+  messagesPerDay?: number;
+  recipientsPerMessage?: number;
+}
+
+export interface IMailDomainAuthority {
+  id: string;
+  owner: IMailResourceOwner;
+  domain: string;
+  addressPattern: IMailAddressPattern;
+  enabled: boolean;
+  status: TMailResourceStatus;
+  inboundTarget?: IMailInboundTarget;
+  outboundPolicy?: {
+    allowedFromPatterns: IMailAddressPattern[];
+    dkimSelector?: string;
+    rateLimits?: IMailRateLimits;
+  };
+  recipientPolicy: IMailRecipientPolicy;
+  spoolPolicy?: IMailSpoolPolicy;
+  createdAt: number;
+  updatedAt: number;
+  createdBy?: string;
+}
+
+export interface IMailAddressBinding {
+  id: string;
+  owner: IMailResourceOwner;
+  address: string;
+  localPart: string;
+  domain: string;
+  enabled: boolean;
+  status: TMailResourceStatus;
+  inboundTarget?: IMailInboundTarget;
+  outboundIdentityId?: string;
+  recipientPolicy?: IMailRecipientPolicy;
+  spoolPolicy?: IMailSpoolPolicy;
+  createdAt: number;
+  updatedAt: number;
+  createdBy?: string;
+}
+
+export interface IMailCredentialPublic {
+  id: string;
+  type: TMailCredentialType;
+  status: TMailCredentialStatus;
+  username?: string;
+  scopes?: string[];
+  createdAt: number;
+  updatedAt: number;
+  lastRotatedAt?: number;
+}
+
+export interface IMailCredentialOneTimeSecret {
+  credential: IMailCredentialPublic;
+  secret: string;
+  secretShownOnce: true;
+}
+
+export interface IMailOutboundIdentity {
+  id: string;
+  owner: IMailResourceOwner;
+  enabled: boolean;
+  status: TMailResourceStatus;
+  allowedFromPatterns: IMailAddressPattern[];
+  defaultFrom?: string;
+  domain?: string;
+  dkimSelector?: string;
+  credential?: IMailCredentialPublic;
+  rateLimits?: IMailRateLimits;
+  createdAt: number;
+  updatedAt: number;
+  createdBy?: string;
+}
+
+export interface IWorkAppMailBinding {
+  id: string;
+  owner: IMailResourceOwner & { appInstanceId: string };
+  enabled: boolean;
+  status: TMailResourceStatus;
+  domainAuthorityIds?: string[];
+  addressBindingIds?: string[];
+  outboundIdentityIds?: string[];
+  defaultFrom?: string;
+  inboundTarget?: IMailInboundTarget;
+  createdAt: number;
+  updatedAt: number;
+  createdBy?: string;
+}
+
+export interface IMailEnvelope {
+  mailFrom: string;
+  rcptTo: string[];
+}
+
+export interface IMailDeliveryTargetSummary {
+  type: TMailDeliveryTargetType;
+  label?: string;
+  address?: string;
+  url?: string;
+  host?: string;
+  port?: number;
+  serviceRef?: string;
+  method?: string;
+  queueName?: string;
+}
+
+export interface IMailConnectionInfo {
+  protocol: TMailInboundProtocol;
+  remoteAddress?: string;
+  proxyAddress?: string;
+  heloName?: string;
+  tls?: boolean;
+  authUsername?: string;
+  authenticatedCredentialId?: string;
+}
+
+export interface IMailRecipientResolution {
+  recipient: string;
+  action: TMailRecipientResolutionAction;
+  owner?: IMailResourceOwner;
+  domainAuthorityId?: string;
+  addressBindingId?: string;
+  target?: IMailInboundTarget;
+  smtpCode?: number;
+  message?: string;
+  cacheTtlMs?: number;
+}
+
+export interface IMailSpoolItem {
+  id: string;
+  owner?: IMailResourceOwner;
+  direction: TMailSpoolDirection;
+  status: TMailSpoolStatus;
+  envelope: IMailEnvelope;
+  messageId?: string;
+  subject?: string;
+  target?: IMailDeliveryTargetSummary;
+  attempts: number;
+  nextAttemptAt?: number;
+  lastError?: string;
+  rawAvailableUntil?: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface IMailDeliveryAttempt {
+  id: string;
+  spoolItemId: string;
+  target: IMailDeliveryTargetSummary;
+  status: TMailSpoolStatus;
+  startedAt: number;
+  completedAt?: number;
+  smtpCode?: number;
+  response?: string;
+  error?: string;
+}
+
+export interface IMailBounceEvent {
+  id: string;
+  spoolItemId?: string;
+  owner?: IMailResourceOwner;
+  recipient: string;
+  bounceType: TMailBounceType;
+  diagnosticCode?: string;
+  receivedAt: number;
+}
+
+export interface IMailDeliveryStatus {
+  spoolItem?: IMailSpoolItem;
+  attempts: IMailDeliveryAttempt[];
+  bounceEvents?: IMailBounceEvent[];
+}
+
+export interface IMailDeliveryJournalEvent {
+  id: string;
+  spoolItemId: string;
+  owner?: IMailResourceOwner;
+  direction: TMailSpoolDirection;
+  type: TMailDeliveryJournalEventType;
+  status: TMailSpoolStatus;
+  envelope?: IMailEnvelope;
+  target?: IMailDeliveryTargetSummary;
+  attemptId?: string;
+  smtpCode?: number;
+  response?: string;
+  error?: string;
+  message?: string;
+  createdAt: number;
+}
+
+export interface IMailInboundMessagePayload {
+  spoolItemId: string;
+  owner?: IMailResourceOwner;
+  envelope: IMailEnvelope;
+  rawMessage: string;
+  sizeBytes?: number;
+  messageId?: string;
+  subject?: string;
+  headers?: Record<string, string | string[]>;
+  source?: IMailConnectionInfo;
+  receivedAt: number;
+}
+
+export interface IMailOutboundAttachmentPayload {
+  filename: string;
+  contentType?: string;
+  binaryAttachmentString: string;
+}
+
+export interface IMailOutboundMessagePayload {
+  from: string;
+  to: string[];
+  cc?: string[];
+  bcc?: string[];
+  subject: string;
+  text?: string;
+  html?: string;
+  headers?: Record<string, string>;
+  attachments?: IMailOutboundAttachmentPayload[];
+}

package/ts/platform/database.ts

@@ -1,4 +1,4 @@
-export type TPlatformDatabaseEngine = 'postgres' | 'mongodb' | 'mysql' | 'redis';
+export type TPlatformDatabaseEngine = 'postgres' | 'mongodb' | 'mysql' | 'valkey';
 
 export interface IPlatformDatabaseBindingConfig {
   engine: TPlatformDatabaseEngine;

package/ts/requests/index.ts

@@ -17,6 +17,7 @@ import * as identityRequests from './identity.js';
 import * as imageRequests from './image.js';
 import * as informRequests from './inform.js';
 import * as logRequests from './log.js';
+import * as mailRequests from './mail.js';
 import * as networkRequests from './network.js';
 import * as nodeRequests from './node.js';
 import * as platformRequests from './platform.js';
@@ -48,6 +49,7 @@ export {
   imageRequests as image,
   informRequests as inform,
   logRequests as log,
+  mailRequests as mail,
   networkRequests as network,
   nodeRequests as node,
   platformRequests as platform,
@@ -64,3 +66,4 @@ export {
 
 export * from './inform.js';
 export * from './hostedapp.js';
+export * from './mail.js';