@dev.smartpricing/platform-layer 0.0.2

package/_shared/billingCreditNotes.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+import { BillingDocumentSubscriptionSchema } from './billingDocumentSubscriptions.js'
+import { UuidSchema } from './common.js'
+
+export const CreditNoteSchema = z.object({
+  id: UuidSchema,
+  customerId: UuidSchema,
+  invoiceId: UuidSchema.nullable(),
+  /** Generic upstream status string. */
+  status: z.string(),
+  date: z.string().nullable(),
+  total: z.number(),
+  currencyId: UuidSchema,
+  pdfUrl: z.string().nullable(),
+  subscriptions: z.array(BillingDocumentSubscriptionSchema),
+})
+
+export const ListCreditNotesResponseSchema = z.object({
+  items: z.array(CreditNoteSchema),
+})
+
+export type CreditNote = z.infer<typeof CreditNoteSchema>
+
+export type ListCreditNotesResponse = z.infer<typeof ListCreditNotesResponseSchema>

package/_shared/billingDocumentSubscriptions.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+import { UuidSchema } from './common.js'
+
+export const BillingDocumentProductSchema = z.object({
+  id: UuidSchema,
+})
+
+export const BillingDocumentItemProductSchema = z.object({
+  product: BillingDocumentProductSchema,
+})
+
+export const BillingDocumentItemSchema = z.object({
+  id: UuidSchema,
+  itemProducts: z.array(BillingDocumentItemProductSchema),
+})
+
+export const BillingDocumentItemPriceSchema = z.object({
+  id: UuidSchema,
+  item: BillingDocumentItemSchema,
+})
+
+export const BillingDocumentSubscriptionItemSchema = z.object({
+  itemPrice: BillingDocumentItemPriceSchema,
+})
+
+export const BillingDocumentSubscriptionSchema = z.object({
+  id: UuidSchema,
+  subscriptionItems: z.array(BillingDocumentSubscriptionItemSchema),
+})
+
+export type BillingDocumentProduct = z.infer<typeof BillingDocumentProductSchema>
+export type BillingDocumentItemProduct = z.infer<typeof BillingDocumentItemProductSchema>
+export type BillingDocumentItem = z.infer<typeof BillingDocumentItemSchema>
+export type BillingDocumentItemPrice = z.infer<typeof BillingDocumentItemPriceSchema>
+export type BillingDocumentSubscriptionItem = z.infer<typeof BillingDocumentSubscriptionItemSchema>
+export type BillingDocumentSubscription = z.infer<typeof BillingDocumentSubscriptionSchema>

package/_shared/billingDocuments.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+import { UuidSchema } from './common.js'
+
+export const BillingDocumentTypeSchema = z.enum(['invoice', 'credit_note'])
+
+export const BillingDocumentRowSchema = z.object({
+  type: BillingDocumentTypeSchema,
+  id: UuidSchema,
+  customerId: UuidSchema,
+  status: z.string(),
+  date: z.string().nullable(),
+  total: z.number(),
+  /** Resolved currency code (e.g. "EUR"); null when it can't be resolved. */
+  currency: z.string().nullable(),
+  pdfUrl: z.string().nullable(),
+  /** Subscription IDs linked to this document via Core invoice/credit-note relations. */
+  subscriptionIds: z.array(UuidSchema),
+})
+
+export const ListBillingDocumentsResponseSchema = z.object({
+  items: z.array(BillingDocumentRowSchema),
+})
+
+/** Short-lived signed URL pointing at the document's PDF in object storage. */
+export const BillingDocumentPdfResponseSchema = z.object({
+  url: z.string(),
+})
+
+export type BillingDocumentType = z.infer<typeof BillingDocumentTypeSchema>
+export type BillingDocumentRow = z.infer<typeof BillingDocumentRowSchema>
+export type ListBillingDocumentsResponse = z.infer<typeof ListBillingDocumentsResponseSchema>
+export type BillingDocumentPdfResponse = z.infer<typeof BillingDocumentPdfResponseSchema>

package/_shared/billingInvoices.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+import { BillingDocumentSubscriptionSchema } from './billingDocumentSubscriptions.js'
+import { UuidSchema } from './common.js'
+
+export const InvoiceSchema = z.object({
+  id: UuidSchema,
+  customerId: UuidSchema,
+  /** Generic upstream status string. */
+  status: z.string(),
+  date: z.string().nullable(),
+  dueDate: z.string().nullable(),
+  total: z.number(),
+  currencyId: UuidSchema,
+  pdfUrl: z.string().nullable(),
+  subscriptions: z.array(BillingDocumentSubscriptionSchema),
+})
+
+export const ListInvoicesResponseSchema = z.object({
+  items: z.array(InvoiceSchema),
+})
+
+export type Invoice = z.infer<typeof InvoiceSchema>
+
+export type ListInvoicesResponse = z.infer<typeof ListInvoicesResponseSchema>

package/_shared/billingLegalEntities.ts

@@ -0,0 +1,109 @@
+import { z } from 'zod'
+import { UuidSchema } from './common.js'
+
+export const LegalEntityTypeSchema = z.enum(['natural_person', 'legal_person'])
+
+/**
+ * Identifier for the Smartness billing entity that issues the invoice for a
+ * given legal entity (Helium S.r.l., Ciaobooking S.r.l., ...). Only relevant
+ * on the create-legal-entity request body — the response does not surface it.
+ */
+export const BillingEntityCodeSchema = z.enum(['helium', 'ciaobooking'])
+
+export const LegalEntitySchema = z.object({
+  id: UuidSchema,
+  organizationId: UuidSchema,
+  entityType: LegalEntityTypeSchema,
+  firstName: z.string().nullable(),
+  lastName: z.string().nullable(),
+  companyName: z.string().nullable(),
+  email: z.string().email(),
+  countryCode: z.string().length(2),
+  city: z.string(),
+})
+
+export const ListLegalEntitiesResponseSchema = z.object({
+  items: z.array(LegalEntitySchema),
+})
+
+/**
+ * Full legal-entity shape used by the edit form. Unlike {@link LegalEntitySchema}
+ * (the trimmed list/overview projection) this carries every editable billing field
+ * plus the read-only identity/audit columns, so the modal can seed every input.
+ */
+export const LegalEntityDetailSchema = z.object({
+  id: UuidSchema,
+  organizationId: UuidSchema,
+  entityType: LegalEntityTypeSchema,
+  firstName: z.string().nullable(),
+  lastName: z.string().nullable(),
+  companyName: z.string().nullable(),
+  email: z.string().email(),
+  pec: z.string().nullable(),
+  phoneCountryCode: z.string().nullable(),
+  phone: z.string().nullable(),
+  address: z.string(),
+  postcode: z.string(),
+  city: z.string(),
+  state: z.string(),
+  countryCode: z.string(),
+  vatNumberPrefix: z.string().nullable(),
+  vatNumber: z.string().nullable(),
+  vatNumberStatus: z.string().nullable(),
+  taxCode: z.string().nullable(),
+  einvoiceRoutingCode: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+})
+
+/**
+ * PATCH body for editing a legal entity. Every field is optional (partial update).
+ * Identity-defining columns (`entityType`, `organizationId`) are intentionally absent:
+ * core-api rejects them as immutable, and a large edit to a protected field
+ * (company / first / last name, VAT, tax code) is bounced to the subentro flow.
+ */
+export const UpdateLegalEntityRequestSchema = z.object({
+  firstName: z.string().optional(),
+  lastName: z.string().optional(),
+  companyName: z.string().optional(),
+  email: z.string().email().optional(),
+  pec: z.string().nullable().optional(),
+  phoneCountryCode: z.string().nullable().optional(),
+  phone: z.string().nullable().optional(),
+  address: z.string().optional(),
+  postcode: z.string().optional(),
+  city: z.string().optional(),
+  state: z.string().optional(),
+  countryCode: z.string().optional(),
+  vatNumberPrefix: z.string().optional(),
+  vatNumber: z.string().optional(),
+  taxCode: z.string().optional(),
+  einvoiceRoutingCode: z.string().optional(),
+})
+
+/**
+ * "Subentro" request: raised when core-api rejects a too-large edit to a protected
+ * field. Carries the field-level before/after the user proposed so ops can action the
+ * change (a name/VAT/tax-code change is effectively a different entity, not a typo fix).
+ */
+export const RequestLegalEntityChangeRequestSchema = z.object({
+  changes: z
+    .array(
+      z.object({
+        field: z.string(),
+        from: z.string().nullable(),
+        to: z.string().nullable(),
+      })
+    )
+    .min(1),
+  note: z.string().optional(),
+})
+
+export type LegalEntityType = z.infer<typeof LegalEntityTypeSchema>
+export type BillingEntityCode = z.infer<typeof BillingEntityCodeSchema>
+export type LegalEntity = z.infer<typeof LegalEntitySchema>
+
+export type ListLegalEntitiesResponse = z.infer<typeof ListLegalEntitiesResponseSchema>
+export type LegalEntityDetail = z.infer<typeof LegalEntityDetailSchema>
+export type UpdateLegalEntityRequest = z.infer<typeof UpdateLegalEntityRequestSchema>
+export type RequestLegalEntityChangeRequest = z.infer<typeof RequestLegalEntityChangeRequestSchema>

package/_shared/billingOverview.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+import { UuidSchema } from './common.js'
+import { LegalEntityDetailSchema } from './billingLegalEntities.js'
+import { PaymentMethodSchema } from './billingPaymentMethods.js'
+import { SubscriptionSchema } from './billingSubscriptions.js'
+
+export const BillingOverviewResponseSchema = z.object({
+  // Full per-entity projection: the list already fetches every billing field from core-api, so
+  // the overview surfaces them (the details card renders address/tax id/PEC/phone without a refetch).
+  legalEntities: z.array(LegalEntityDetailSchema),
+  subscriptions: z.array(SubscriptionSchema),
+  paymentMethodsByLegalEntityId: z.record(UuidSchema, z.array(PaymentMethodSchema)),
+})
+
+export type BillingOverviewResponse = z.infer<typeof BillingOverviewResponseSchema>

package/_shared/billingPaymentMethods.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod'
+import { UuidSchema } from './common.js'
+
+export const PaymentMethodTypeSchema = z.enum(['card', 'direct_debit'])
+
+export const PaymentMethodSchema = z.object({
+  id: UuidSchema,
+  customerId: UuidSchema,
+  type: PaymentMethodTypeSchema,
+  /** Brand for cards (e.g. "Visa"); bank name for direct debit. */
+  label: z.string(),
+  /** Last 4 digits of the card or IBAN tail. */
+  last4: z.string(),
+  /** Cards only. */
+  expiryMonth: z.number().int().min(1).max(12).nullable(),
+  expiryYear: z.number().int().nullable(),
+  status: z.string(),
+  /** True when this is the customer's primary payment source (from the overview). */
+  isPrimary: z.boolean(),
+})
+
+export const ListPaymentMethodsResponseSchema = z.object({
+  items: z.array(PaymentMethodSchema),
+})
+
+export const SetPrimaryPaymentMethodRequestSchema = z.object({
+  customerId: UuidSchema,
+  paymentMethodId: UuidSchema,
+})
+
+export const SetPrimaryPaymentMethodResponseSchema = z.object({
+  customerId: UuidSchema,
+  primaryPaymentSourceId: UuidSchema,
+})
+
+/**
+ * Card add (step 1): the frontend tokenizes the card with Stripe Elements, then
+ * exchanges the PaymentMethod id for a SetupIntent client_secret to confirm (SCA).
+ */
+export const CreateSetupIntentRequestSchema = z.object({
+  customerId: UuidSchema,
+  stripePaymentMethodId: z.string().min(1),
+})
+
+export const CreateSetupIntentResponseSchema = z.object({
+  stripeCustomerId: z.string(),
+  stripePaymentMethodId: z.string(),
+  clientSecret: z.string(),
+})
+
+/** Card add (step 2): create the source from the confirmed SetupIntent. Targets one customer. */
+export const CreateCardPaymentMethodRequestSchema = z.object({
+  type: z.literal('card'),
+  customerId: UuidSchema,
+  setupIntentId: z.string().min(1),
+  stripePaymentMethodId: z.string().min(1),
+})
+
+/** IBAN/SEPA add: targets the legal entity; the backend fans out to its eligible EUR customers. */
+export const CreateDirectDebitPaymentMethodRequestSchema = z.object({
+  type: z.literal('direct_debit'),
+  legalEntityId: UuidSchema,
+  iban: z.string().min(1),
+  firstName: z.string().min(1),
+  lastName: z.string().min(1),
+  email: z.string().optional(),
+})
+
+export const CreatePaymentMethodRequestSchema = z.discriminatedUnion('type', [
+  CreateCardPaymentMethodRequestSchema,
+  CreateDirectDebitPaymentMethodRequestSchema,
+])
+
+/** One item for a card, one per customer for the IBAN fan-out, plus per-customer failures. */
+export const CreatePaymentMethodsResponseSchema = z.object({
+  items: z.array(PaymentMethodSchema),
+  failed: z.array(z.object({ customerId: UuidSchema, reason: z.string() })),
+})
+
+export type PaymentMethodType = z.infer<typeof PaymentMethodTypeSchema>
+export type PaymentMethod = z.infer<typeof PaymentMethodSchema>
+
+export type ListPaymentMethodsResponse = z.infer<typeof ListPaymentMethodsResponseSchema>
+export type SetPrimaryPaymentMethodRequest = z.infer<typeof SetPrimaryPaymentMethodRequestSchema>
+export type SetPrimaryPaymentMethodResponse = z.infer<typeof SetPrimaryPaymentMethodResponseSchema>
+export type CreateSetupIntentRequest = z.infer<typeof CreateSetupIntentRequestSchema>
+export type CreateSetupIntentResponse = z.infer<typeof CreateSetupIntentResponseSchema>
+export type CreatePaymentMethodRequest = z.infer<typeof CreatePaymentMethodRequestSchema>
+export type CreatePaymentMethodsResponse = z.infer<typeof CreatePaymentMethodsResponseSchema>

package/_shared/billingSubscriptions.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+import { UuidSchema } from './common.js'
+
+export const BillingPeriodUnitSchema = z.enum(['day', 'week', 'month', 'year'])
+
+export const SubscriptionPropertySchema = z.object({
+  id: UuidSchema,
+  name: z.string(),
+})
+
+export const SubscriptionSchema = z.object({
+  id: UuidSchema,
+  customerId: UuidSchema,
+  /**
+   * The anagrafica (legal entity) that owns this subscription, resolved upstream via
+   * subscription → customer → legal_entity. This is the authoritative grouping key for
+   * the billing UI; never re-derive the link from payment methods. Nullable only for the
+   * pathological deleted-customer case core-api leaves unresolved.
+   */
+  legalEntityId: UuidSchema.nullable(),
+  productName: z.string(),
+  itemPriceName: z.string(),
+  /** Generic upstream status string ("active", "in_trial", "cancelled", ...). */
+  status: z.string(),
+  billingPeriodUnit: BillingPeriodUnitSchema.nullable(),
+  billingPeriod: z.number().int().nullable(),
+  mrr: z.number().nullable(),
+  currencyId: UuidSchema,
+  /** Resolved currency code (e.g. "EUR"); null when it can't be resolved. Used to gate SEPA. */
+  currency: z.string().nullable(),
+  unitsCount: z.number().int().nullable(),
+  nextBillingAt: z.string().nullable(),
+  startedAt: z.string().nullable(),
+  properties: z.array(SubscriptionPropertySchema),
+})
+
+export const ListSubscriptionsResponseSchema = z.object({
+  items: z.array(SubscriptionSchema),
+})
+
+export const AttachSubscriptionPropertyResponseSchema = z.object({
+  subscriptionId: UuidSchema,
+  propertyId: UuidSchema,
+  createdAt: z.string(),
+})
+
+export type BillingPeriodUnit = z.infer<typeof BillingPeriodUnitSchema>
+export type SubscriptionProperty = z.infer<typeof SubscriptionPropertySchema>
+export type Subscription = z.infer<typeof SubscriptionSchema>
+
+export type ListSubscriptionsResponse = z.infer<typeof ListSubscriptionsResponseSchema>
+export type AttachSubscriptionPropertyResponse = z.infer<
+  typeof AttachSubscriptionPropertyResponseSchema
+>

package/_shared/common.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod'
+
+export const UuidSchema = z.string().min(1)
+
+export const CurrencySchema = z.enum(['EUR', 'USD', 'GBP'])
+
+/** ISO-8601 date (YYYY-MM-DD). */
+export const IsoDateSchema = z.iso.date()
+
+/** ISO-8601 timestamp (YYYY-MM-DDTHH:mm:ss.sssZ). */
+export const IsoDateTimeSchema = z.iso.datetime()
+
+/**
+ * Membership role inside an organization. Shared across the
+ * organizations and members contexts so the two domains can never drift.
+ */
+export const RoleSchema = z.enum(['owner', 'admin', 'manager', 'viewer'])
+
+export const ApiErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  details: z.record(z.string(), z.unknown()).optional(),
+})
+
+export function listResponseSchema<T extends z.ZodTypeAny>(item: T) {
+  return z.object({ items: z.array(item) })
+}
+
+export type Uuid = z.infer<typeof UuidSchema>
+export type Currency = z.infer<typeof CurrencySchema>
+export type IsoDate = z.infer<typeof IsoDateSchema>
+export type IsoDateTime = z.infer<typeof IsoDateTimeSchema>
+export type Role = z.infer<typeof RoleSchema>
+export type ApiError = z.infer<typeof ApiErrorSchema>

package/_shared/crossSelling.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod'
+
+export const ModulePlanSchema = z.enum(['STANDARD', 'PREMIUM', 'ULTRA']).nullable()
+
+export const CrossSellModulePlansSchema = z.object({
+  pricing: ModulePlanSchema,
+  connect: ModulePlanSchema,
+  pms: ModulePlanSchema,
+  chat: ModulePlanSchema,
+  site: ModulePlanSchema,
+})
+
+export const GetCrossSellingResponseSchema = z.object({
+  availablePlans: CrossSellModulePlansSchema,
+  isUsingPmsGoldPartner: z.boolean(),
+  isUsingPricingGoldPartner: z.boolean(),
+})
+
+export type ModulePlan = z.infer<typeof ModulePlanSchema>
+export type CrossSellModulePlans = z.infer<typeof CrossSellModulePlansSchema>
+export type GetCrossSellingResponse = z.infer<typeof GetCrossSellingResponseSchema>

package/_shared/index.ts

@@ -0,0 +1,22 @@
+export * from './common.js'
+export * from './password.js'
+export * from './user.js'
+export * from './meContext.js'
+export * from './organizationContext.js'
+export * from './organizations.js'
+export * from './members.js'
+export * from './properties.js'
+export * from './unitTypes.js'
+export * from './products.js'
+export * from './billingSubscriptions.js'
+export * from './billingDocumentSubscriptions.js'
+export * from './billingInvoices.js'
+export * from './billingCreditNotes.js'
+export * from './billingPaymentMethods.js'
+export * from './billingLegalEntities.js'
+export * from './billingOverview.js'
+export * from './billingDocuments.js'
+export * from './crossSelling.js'
+export * from './permissions.js'
+export * from './mfa.js'
+export * from './subscriptionCancellation.js'

package/_shared/meContext.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+import { ListOrganizationsResponseSchema } from './organizations.js'
+import { UserSchema } from './user.js'
+
+export const AuthStateSchema = z.enum(['pwd_authenticated', 'totp_verified'])
+export type AuthStateType = z.infer<typeof AuthStateSchema>
+
+export const MeContextResponseSchema = z.object({
+  user: UserSchema,
+  organizations: ListOrganizationsResponseSchema.shape.items,
+  /** Current session authentication state. `pwd_authenticated` = password only; `totp_verified` = TOTP step completed. */
+  auth_state: AuthStateSchema,
+})
+
+export type MeContextResponse = z.infer<typeof MeContextResponseSchema>

package/_shared/members.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod'
+import type { Role } from './common.js'
+import { IsoDateTimeSchema, RoleSchema, UuidSchema } from './common.js'
+
+export const MemberSchema = z.object({
+  id: UuidSchema,
+  organizationId: UuidSchema,
+  firstName: z.string(),
+  lastName: z.string(),
+  email: z.string().email(),
+  role: RoleSchema,
+  lastActiveAt: IsoDateTimeSchema,
+})
+
+export const ListMembersResponseSchema = z.object({
+  items: z.array(MemberSchema),
+})
+
+/** Re-exported under the members namespace for ergonomics. */
+export type MemberRole = Role
+export type Member = z.infer<typeof MemberSchema>
+
+export type ListMembersResponse = z.infer<typeof ListMembersResponseSchema>

package/_shared/mfa.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod'
+
+// ── Step-up (OTP verification) ──────────────────────────────────────
+
+export const MfaStepUpRequestSchema = z.union([
+  z.object({ totpCode: z.string() }),
+  z.object({ recoveryCode: z.string() }),
+])
+
+/**
+ * Returns `{ enrolled: false }` when the user has no MFA enrollment,
+ * or an empty object on successful verification.
+ */
+export const MfaStepUpResponseSchema = z.union([
+  z.object({ enrolled: z.literal(false) }),
+  z.object({}),
+])
+
+// ── Setup ───────────────────────────────────────────────────────────
+
+export const MfaSetupResponseSchema = z.object({
+  enrollment_id: z.string(),
+  secret: z.string(),
+  qr_dataurl: z.string(),
+})
+
+// ── Finalize ────────────────────────────────────────────────────────
+
+export const MfaFinalizeRequestSchema = z.object({
+  enrollmentId: z.string(),
+  totpCode: z.string(),
+})
+
+export const MfaFinalizeResponseSchema = z.object({
+  recovery_codes: z.array(z.string()),
+})
+
+// ── Disable ─────────────────────────────────────────────────────────
+
+/** Exactly one verification method must be provided; the backend enforces the constraint. */
+export const MfaDisableRequestSchema = z.object({
+  totpCode: z.string().optional(),
+  recoveryCode: z.string().optional(),
+  password: z.string().optional(),
+})
+
+export const MfaDisableResponseSchema = z.object({
+  status: z.literal('disabled'),
+})
+
+// ── Regenerate recovery codes ───────────────────────────────────────
+
+export const MfaRegenerateRecoveryCodesRequestSchema = z.object({
+  totpCode: z.string(),
+})
+
+export const MfaRegenerateRecoveryCodesResponseSchema = z.object({
+  recovery_codes: z.array(z.string()),
+})
+
+// ── Types ───────────────────────────────────────────────────────────
+
+export type MfaStepUpRequest = z.infer<typeof MfaStepUpRequestSchema>
+export type MfaStepUpResponse = z.infer<typeof MfaStepUpResponseSchema>
+
+export type MfaSetupResponse = z.infer<typeof MfaSetupResponseSchema>
+
+export type MfaFinalizeRequest = z.infer<typeof MfaFinalizeRequestSchema>
+export type MfaFinalizeResponse = z.infer<typeof MfaFinalizeResponseSchema>
+
+export type MfaDisableRequest = z.infer<typeof MfaDisableRequestSchema>
+export type MfaDisableResponse = z.infer<typeof MfaDisableResponseSchema>
+
+export type MfaRegenerateRecoveryCodesRequest = z.infer<typeof MfaRegenerateRecoveryCodesRequestSchema>
+export type MfaRegenerateRecoveryCodesResponse = z.infer<typeof MfaRegenerateRecoveryCodesResponseSchema>

package/_shared/organizationContext.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod'
+import { MemberSchema } from './members.js'
+import { OrgProductRowSchema } from './products.js'
+import { PropertySchema } from './properties.js'
+import { UnitTypeSchema } from './unitTypes.js'
+
+export const PropertyWithUnitTypesSchema = PropertySchema.extend({
+  unitTypes: z.array(UnitTypeSchema),
+})
+
+export const OrganizationContextResponseSchema = z.object({
+  products: z.array(OrgProductRowSchema),
+  members: z.array(MemberSchema),
+  properties: z.array(PropertyWithUnitTypesSchema),
+})
+
+export type PropertyWithUnitTypes = z.infer<typeof PropertyWithUnitTypesSchema>
+export type OrganizationContextResponse = z.infer<typeof OrganizationContextResponseSchema>

package/_shared/organizations.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod'
+import type { Role } from './common.js'
+import { UuidSchema } from './common.js'
+
+export const OrganizationSchema = z.object({
+  id: UuidSchema,
+  name: z.string(),
+})
+
+export const OrganizationRoleSchema = z.object({
+  id: UuidSchema,
+  name: z.string(),
+})
+
+/**
+ * Re-exported under the organizations namespace for ergonomics; downstream
+ * consumers (org switcher, etc.) keep using the same `Role` enum.
+ */
+export type OrganizationRole = Role
+
+/**
+ * Org-level role assignment for a user. Returned by
+ * `GET /core/v3/users/{id}/organizations` and drives the org switcher.
+ */
+export const OrganizationMembershipSchema = z.object({
+  organizationId: UuidSchema,
+  organizationName: z.string(),
+  role: OrganizationRoleSchema,
+  productId: UuidSchema.nullable(),
+  productName: z.string().nullable(),
+})
+
+export const ListOrganizationsResponseSchema = z.object({
+  items: z.array(OrganizationMembershipSchema),
+})
+
+export const SetActiveOrganizationRequestSchema = z.object({
+  organizationId: UuidSchema,
+})
+
+export type Organization = z.infer<typeof OrganizationSchema>
+export type OrganizationRoleRef = z.infer<typeof OrganizationRoleSchema>
+export type OrganizationMembership = z.infer<typeof OrganizationMembershipSchema>
+
+export type ListOrganizationsResponse = z.infer<typeof ListOrganizationsResponseSchema>
+export type SetActiveOrganizationRequest = z.infer<typeof SetActiveOrganizationRequestSchema>

package/_shared/password.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod'
+
+export const PASSWORD_MIN_LENGTH = 10
+export const PASSWORD_MAX_LENGTH = 128
+
+/**
+ * Shared password policy used by the BFF backend (authoritative) and the SPA
+ * (UX gating). Only enforces what can be checked synchronously without external
+ * services: length bounds. Strength scoring (zxcvbn) and breach lookups (HIBP)
+ * run server-side inside the password use-cases — they can fail-open on outage
+ * without affecting the client validation contract.
+ */
+export const PasswordSchema = z
+  .string()
+  .min(PASSWORD_MIN_LENGTH)
+  .max(PASSWORD_MAX_LENGTH)
+
+export type PasswordPolicyCode =
+  | 'password.too_short'
+  | 'password.too_long'
+  | 'password.too_weak'
+  | 'password.breached'