@endevops/peppol-schema 0.1.0-beta.3 → 0.1.0-beta.5

package/src/{effect → schemas}/peppol-invoice-response-document-actual-response-schema.ts

@@ -1,24 +1,22 @@
 import { Schema } from 'effect';
 
-import { peppolInvoiceResponseDocumentActualResponseStatusSchema } from '#/effect/peppol-invoice-response-document-actual-response-status-schema';
-import { peppolIsoDateStringSchema } from '#/effect/peppol-iso-date-string-schema';
 import { invoiceResponseCodeNeedsSchema } from '#/invoice-response-codes/invoice-response-code-needs-schema';
 import { invoiceResponseCodeNotNeedsSchema } from '#/invoice-response-codes/invoice-response-code-not-needs-schema';
+import { PeppolInvoiceResponseDocumentActualResponseStatus } from '#/schemas/peppol-invoice-response-document-actual-response-status-schema';
+import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string';
+import { opaque } from '#/schemas/utils/opaque';
 
-const withStatusCodes = Schema.Literals(invoiceResponseCodeNeedsSchema);
-const withoutStatusCodes = Schema.Literals(invoiceResponseCodeNotNeedsSchema);
+export const withStatusCodes = Schema.Literals(invoiceResponseCodeNeedsSchema);
+export const withoutStatusCodes = Schema.Literals(invoiceResponseCodeNotNeedsSchema);
 
-export const peppolInvoiceResponseDocumentActualResponseSchema = Schema.Union([
+export class PeppolInvoiceResponseDocumentActualResponseWithoutStatus extends opaque<PeppolInvoiceResponseDocumentActualResponseWithoutStatus>()(
   Schema.Struct({
     /**
-     * @remarks
-     *   This is a rejection code that needs clarification in {@link status}
-     *
      * @summary A code stating the status of the invoice in the process.
      *
      * @name `cbc:ResponseCode`
      */
-    responseCode: withStatusCodes,
+    responseCode: withoutStatusCodes,
     /**
      * @description The date when the status became effective.
      *
@@ -29,7 +27,7 @@ export const peppolInvoiceResponseDocumentActualResponseSchema = Schema.Union([
      *
      * @name `cbc:EffectiveDate`
      */
-    effectiveDate: Schema.optional(peppolIsoDateStringSchema),
+    effectiveDate: Schema.optional(PeppolIsoDateString),
     /**
      * @description Clarification is mendatory when the status is UQ-`under query`,RE-`rejected` and `CA`-Conditionally accepted. Clarification may be given as a
      * code, a description or both. If both are used, they must indicate the same clarification.
@@ -38,15 +36,21 @@ export const peppolInvoiceResponseDocumentActualResponseSchema = Schema.Union([
      *
      * @name `cac:Status`
      */
-    status: Schema.Array(peppolInvoiceResponseDocumentActualResponseStatusSchema).check(Schema.isMinLength(1)),
-  }),
+    status: Schema.optional(Schema.Array(PeppolInvoiceResponseDocumentActualResponseStatus)),
+  })
+) {}
+
+export class PeppolInvoiceResponseDocumentActualResponseWithStatus extends opaque<PeppolInvoiceResponseDocumentActualResponseWithStatus>()(
   Schema.Struct({
     /**
+     * @remarks
+     *   This is a rejection code that needs clarification in {@link status}
+     *
      * @summary A code stating the status of the invoice in the process.
      *
      * @name `cbc:ResponseCode`
      */
-    responseCode: withoutStatusCodes,
+    responseCode: withStatusCodes,
     /**
      * @description The date when the status became effective.
      *
@@ -57,7 +61,7 @@ export const peppolInvoiceResponseDocumentActualResponseSchema = Schema.Union([
      *
      * @name `cbc:EffectiveDate`
      */
-    effectiveDate: Schema.optional(peppolIsoDateStringSchema),
+    effectiveDate: Schema.optional(PeppolIsoDateString),
     /**
      * @description Clarification is mendatory when the status is UQ-`under query`,RE-`rejected` and `CA`-Conditionally accepted. Clarification may be given as a
      * code, a description or both. If both are used, they must indicate the same clarification.
@@ -66,8 +70,13 @@ export const peppolInvoiceResponseDocumentActualResponseSchema = Schema.Union([
      *
      * @name `cac:Status`
      */
-    status: Schema.optional(Schema.Array(peppolInvoiceResponseDocumentActualResponseStatusSchema)),
-  }),
+    status: Schema.Array(PeppolInvoiceResponseDocumentActualResponseStatus).check(Schema.isMinLength(1)),
+  })
+) {}
+
+export const peppolInvoiceResponseDocumentActualResponseSchema = Schema.Union([
+  PeppolInvoiceResponseDocumentActualResponseWithStatus,
+  PeppolInvoiceResponseDocumentActualResponseWithoutStatus,
 ]);
 
 export type InvoiceResponseDocumentActualResponse = typeof peppolInvoiceResponseDocumentActualResponseSchema.Type;

package/src/schemas/peppol-invoice-response-document-actual-response-status-schema.ts

@@ -0,0 +1,63 @@
+import { Schema } from 'effect';
+
+import { peppolInvoiceResponseStatusReasonCodeSchema } from '#/schemas/peppol-invoice-response-status-reason-code-schema';
+import { opaque } from '#/schemas/utils/opaque';
+
+export class PeppolInvoiceResponseCondition extends opaque<PeppolInvoiceResponseCondition>()(
+  Schema.Struct({
+    /**
+     * @description A code defining the type of the detail.
+     *
+     * @example
+     *   `BT-75`;
+     *
+     * @summary Detail type code
+     *
+     * @name `cbc:AttributeId`
+     */
+    attributeId: Schema.String,
+    /**
+     * @description The value of the detail.
+     *
+     * @example
+     *   `EU123456789`;
+     *
+     * @summary Detail value
+     *
+     * @name `cbc:Description`
+     */
+    description: Schema.optional(Schema.String),
+  })
+) {}
+
+export class PeppolInvoiceResponseDocumentActualResponseStatus extends opaque<PeppolInvoiceResponseDocumentActualResponseStatus>()(
+  Schema.Struct({
+    /**
+     * @description A code defining a clarification given for the invoice status.
+     *
+     * @summary Clarification code
+     *
+     * @name `cbc:StatusReasonCode`
+     */
+    statusReasonCode: Schema.optional(peppolInvoiceResponseStatusReasonCodeSchema),
+    /**
+     * @description The description of the clarification given for the invoice status.
+     *
+     * @example
+     *   `TAX reference not found`;
+     *
+     * @summary Clarification description
+     *
+     * @name `cbc:StatusReason
+     */
+    statusReason: Schema.optional(Schema.String),
+    /**
+     * @summary Condition
+     *
+     * @name `cac:Condition`
+     */
+    condition: Schema.optional(Schema.Array(PeppolInvoiceResponseCondition)),
+  })
+) {}
+
+export type InvoiceResponseDocumentActualResponseStatus = PeppolInvoiceResponseDocumentActualResponseStatus;

package/src/schemas/peppol-invoice-response-schema.ts

@@ -0,0 +1,176 @@
+import { Schema, Struct } from 'effect';
+
+import { INVOICE_RESPONSE_PROFILE_ID } from '#/constants/invoice-response-profile-id';
+import { PeppolContact } from '#/schemas/fields/peppol-contact-schema';
+import { PeppolIdentifier } from '#/schemas/fields/peppol-identifier-schema';
+import { PeppolPartyLegalEntity } from '#/schemas/fields/peppol-party-legal-entity-schema';
+import { peppolInvoiceResponseDocumentActualResponseSchema } from '#/schemas/peppol-invoice-response-document-actual-response-schema';
+import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string';
+import { PeppolMessageLevelResponseParty } from '#/schemas/peppol-message-level-response-party-schema';
+import { PeppolMessageLevelResponse } from '#/schemas/peppol-message-level-response-schema';
+import { opaque } from '#/schemas/utils/opaque';
+import { peppolDocumentTypeCodeSchema } from '#/schemas/values/peppol-document-type-code-schema';
+
+export class PeppolInvoiceResponseDocumentResponsePartyName extends opaque<PeppolInvoiceResponseDocumentResponsePartyName>()(
+  Schema.Struct({
+    /**
+     * @description - The party that issued the reference invoice
+     * - The party who the referenced invoice is issued.
+     *
+     * @summary Seller/Buyer party name
+     *
+     * @name `cbc:Name`
+     */
+    name: Schema.String,
+  })
+) {}
+
+export class PeppolInvoiceResponseParty extends opaque<PeppolInvoiceResponseParty>()(
+  PeppolMessageLevelResponseParty.pipe(
+    Schema.fieldsAssign({
+      /**
+       * @summary Party partyIdentification
+       */
+      partyIdentification: Schema.optional(PeppolIdentifier),
+      partyLegalEntity: PeppolPartyLegalEntity.mapFields(Struct.pick(['registrationName'])),
+    })
+  )
+) {}
+
+export class PeppolInvoiceResponseSenderParty extends opaque<PeppolInvoiceResponseSenderParty>()(
+  PeppolInvoiceResponseParty.pipe(
+    Schema.fieldsAssign({
+      /**
+       * @summary Contact information
+       *
+       * @name `cac:Contact`
+       */
+      contact: Schema.optional(PeppolContact),
+    })
+  )
+) {}
+
+/**
+ * @description Party schema used under `cac:DocumentReference/(cac:IssuerParty|cac:RecipientParty)`
+ */
+export class PeppolInvoiceResponseDocumentResponseParty extends opaque<PeppolInvoiceResponseDocumentResponseParty>()(
+  Schema.Struct({
+    /**
+     * @summary Party partyIdentification
+     */
+    partyIdentification: Schema.optional(PeppolIdentifier),
+    /**
+     * @example
+     *   Seller Business Name AS
+     *
+     * @name cac:PartyName
+     */
+    partyName: PeppolInvoiceResponseDocumentResponsePartyName,
+  })
+) {}
+
+export type PeppolInvoiceDocumentResponseParty = PeppolInvoiceResponseDocumentResponseParty;
+
+export class PeppolInvoiceResponseDocumentReference extends opaque<PeppolInvoiceResponseDocumentReference>()(
+  Schema.Struct({
+    /**
+     * @description An identifier for the invoice that the status applies to. The invoice identifier must be of the main invoice number that appears in the invoice
+     * itself.
+     *
+     * @example
+     *   `inv-99876`;
+     *
+     * @summary Invoice identifier
+     *
+     * @name `cbc:ID`
+     */
+    id: Schema.String,
+    /**
+     * @description The date on which the referenced invoice was issued.
+     *
+     * @example
+     *   `2018-08-01`;
+     *
+     * @summary Invoice issue date
+     *
+     * @name `cbc:IssueDate`
+     */
+    issueDate: Schema.optional(PeppolIsoDateString),
+    /**
+     * @example
+     *   `380`;
+     *
+     * @summary Identifier type code
+     */
+    documentTypeCode: peppolDocumentTypeCodeSchema,
+  })
+) {}
+
+export class PeppolInvoiceResponseDocumentResponse extends opaque<PeppolInvoiceResponseDocumentResponse>()(
+  Schema.Struct({
+    /**
+     * @summary Response information
+     *
+     * @name `cac:Response`
+     *
+     * @cardinality (1..1)
+     */
+    response: peppolInvoiceResponseDocumentActualResponseSchema,
+    /**
+     * @summary Document reference
+     *
+     * @name `cac:DocumentReference`
+     */
+    documentReference: PeppolInvoiceResponseDocumentReference,
+    /**
+     * @summary Seller party information
+     *
+     * @name `cac:IssuerParty`
+     */
+    issuerParty: Schema.optional(PeppolInvoiceResponseDocumentResponseParty),
+    /**
+     * @summary Buyer party information
+     *
+     * @name `cac:RecipientParty`
+     */
+    recipientParty: Schema.optional(PeppolInvoiceResponseDocumentResponseParty),
+  })
+) {}
+
+/**
+ * @description The invoice response is a descendant of the message level response with more fields. Effect port of `invoiceResponseSchema`
+ * (`z.extend(messageLevelResponse, ...)` → `messageLevelResponse.pipe(Schema.fieldsAssign(...))`), overriding `profileId` with
+ * `Schema.Literal(INVOICE_RESPONSE_PROFILE_ID)` plus sender/receiver/documentResponse.
+ */
+export class PeppolInvoiceResponse extends opaque<PeppolInvoiceResponse>()(
+  Schema.Struct({
+    ...PeppolMessageLevelResponse.fields,
+    profileId: Schema.Literal(INVOICE_RESPONSE_PROFILE_ID),
+    /**
+     * @description The party sending an electronic message level response message back to the sending party of the business document.
+     *
+     * @summary Sender information
+     */
+    senderParty: PeppolInvoiceResponseSenderParty,
+    /**
+     * @description The party, an electronic message level response was addressed to, and who is supposed to process the message level response. This is the same
+     * party as the sender of the business document.
+     *
+     * @summary Receiver information
+     */
+    receiverParty: PeppolInvoiceResponseParty,
+    /**
+     * @description General comments or instructions that are revelant to the response as a whole.
+     *
+     * @example
+     *   `Please refere to previous email exchange regarding this invoice.`;
+     *
+     * @summary Invoice response note
+     */
+    note: Schema.optional(Schema.String),
+    /**
+     * @summary Document response
+     */
+    documentResponse: PeppolInvoiceResponseDocumentResponse,
+  })
+) {}

package/src/schemas/peppol-invoice-response-status-reason-code-schema.ts

@@ -0,0 +1,40 @@
+import { Schema } from 'effect';
+
+import { opaque } from '#/schemas/utils/opaque';
+import { opStatusActionSchema } from '#/schemas/values/op-status-action-schema';
+import { opStatusReasonSchema } from '#/schemas/values/op-status-reason-schema';
+
+export class PeppolInvoiceResponseStatusReasonCodeReason extends opaque<PeppolInvoiceResponseStatusReasonCodeReason>()(
+  Schema.Struct({
+    value: opStatusReasonSchema,
+    /**
+     * @description List identifier for clarification.
+     *
+     * @summary List identifier
+     *
+     * @name `@listId`
+     */
+    listId: Schema.Literal('OPStatusReason'),
+  })
+) {}
+
+export class PeppolInvoiceResponseStatusReasonCodeAction extends opaque<PeppolInvoiceResponseStatusReasonCodeAction>()(
+  Schema.Struct({
+    value: opStatusActionSchema,
+    /**
+     * @description List identifier for clarification.
+     *
+     * @summary List identifier
+     *
+     * @name `@listId`
+     */
+    listId: Schema.Literal('OPStatusAction'),
+  })
+) {}
+
+export const peppolInvoiceResponseStatusReasonCodeSchema = Schema.Union([
+  PeppolInvoiceResponseStatusReasonCodeAction,
+  PeppolInvoiceResponseStatusReasonCodeReason,
+]);
+
+export type PeppolInvoiceResponseStatusReasonCode = typeof peppolInvoiceResponseStatusReasonCodeSchema.Type;

package/src/schemas/peppol-invoice-schema.ts

@@ -0,0 +1,45 @@
+import { Schema } from 'effect';
+
+import { PeppolInvoiceLine } from '#/schemas/fields/peppol-invoice-line-schema';
+import { PeppolBillingBase } from '#/schemas/peppol-billing-base-schema';
+import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string';
+import { opaque } from '#/schemas/utils/opaque';
+import { invoiceTypeCodeSchema } from '#/schemas/values/invoice-type-code-schema';
+
+class PeppolProjectReference extends opaque<PeppolProjectReference>()(Schema.Struct({ id: Schema.String })) {}
+
+export class PeppolInvoice extends opaque<PeppolInvoice>()(
+  Schema.Struct({
+    ...PeppolBillingBase.fields,
+    /**
+     * @example
+     *   `2017-11-01`;
+     *
+     * @summary Payment due date
+     *
+     * @name cbc:DueDate
+     */
+    dueDate: Schema.optional(PeppolIsoDateString),
+    /**
+     * @summary INVOICE LINE
+     *
+     * @name cac:InvoiceLine
+     */
+    invoiceLines: Schema.Array(PeppolInvoiceLine).check(Schema.isMinLength(1)),
+    /**
+     * @example
+     *   `380`;
+     *
+     * @summary Invoice type code
+     *
+     * @name cbc:InvoiceTypeCode
+     */
+    invoiceTypeCode: invoiceTypeCodeSchema,
+    /**
+     * @summary PROJECT REFERENCE
+     *
+     * @name cac:ProjectReference
+     */
+    projectReference: Schema.optional(PeppolProjectReference),
+  })
+) {}

package/src/schemas/peppol-iso-date-string.ts

@@ -0,0 +1,20 @@
+import { DateTime, Schema, SchemaGetter } from 'effect';
+
+import { opaque } from '#/schemas/utils/opaque';
+
+/**
+ * @description ISO 8601 calendar date string (`YYYY-MM-DD`). Effect port of `dateOnly` (`z.iso.date()`): keeps the value as a plain string and only validates the
+ * shape — no `Date` conversion.
+ *
+ * @format date
+ *
+ * @see PEPPOL-EN16931-F001: A date MUST be formatted YYYY-MM-DD.
+ */
+export class PeppolIsoDateString extends opaque<PeppolIsoDateString>()(
+  Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}Z?$/)).pipe(
+    Schema.decodeTo(Schema.DateTimeUtc, {
+      decode: SchemaGetter.dateTimeUtcFromInput().map(DateTime.removeTime),
+      encode: SchemaGetter.transform(DateTime.formatIsoDate),
+    })
+  )
+) {}

package/src/schemas/peppol-message-level-response-document-response-schema.ts

@@ -0,0 +1,35 @@
+import { Schema } from 'effect';
+
+import { PeppolDocumentResponseDocumentReference } from '#/schemas/peppol-document-response-document-reference-schema';
+import { PeppolDocumentResponseDocument } from '#/schemas/peppol-document-response-document-schema';
+import { PeppolDocumentResponseLineResponse } from '#/schemas/peppol-document-response-line-response-schema';
+import { opaque } from '#/schemas/utils/opaque';
+
+export class PeppolMessageLevelResponseDocumentResponse extends opaque<PeppolMessageLevelResponseDocumentResponse>()(
+  Schema.Struct({
+    /**
+     * @summary Response information
+     *
+     * @name `cac:Response`
+     *
+     * @cardinality (1..1)
+     */
+    response: PeppolDocumentResponseDocument,
+    /**
+     * @description The document reference is used to provide a reference to the envelope of the business document on which the message level response is based.
+     * The message level response message may only cover exactly one business document. The element
+     * `cac:DocumentResponse/cac:DocumentReference/cbc:ID` **MUST** contain the instance identifier of the envelope of the original business
+     * document.
+     *
+     * @summary Document reference
+     */
+    documentReference: PeppolDocumentResponseDocumentReference,
+    /**
+     * @description A response to a particular line in the document. If the document response is negative (code='RE'), the line response element is used to specify
+     * the errors in the business document.
+     *
+     * @summary Line response information
+     */
+    lineResponse: Schema.Array(PeppolDocumentResponseLineResponse),
+  })
+) {}

package/src/schemas/peppol-message-level-response-party-schema.ts

@@ -0,0 +1,20 @@
+import { Schema } from 'effect';
+
+import { PeppolIdentifier } from '#/schemas/fields/peppol-identifier-schema';
+import { opaque } from '#/schemas/utils/opaque';
+
+export class PeppolMessageLevelResponseParty extends opaque<PeppolMessageLevelResponseParty>()(
+  Schema.Struct({
+    /**
+     * @description Identifies the sender party's electronic address.
+     *
+     * @example
+     *   7300010000001;
+     *
+     * @summary Sender/Receiver party's electronic address
+     *
+     * @name `cbc:EndpointID (+ @schemeID)`
+     */
+    endpointId: Schema.optional(PeppolIdentifier),
+  })
+) {}

package/src/schemas/peppol-message-level-response-schema.ts

@@ -0,0 +1,98 @@
+import { Schema } from 'effect';
+
+import { MESSAGE_LEVEL_RESPONSE_PROFILE_ID } from '#/constants/message-level-response-profile-id';
+import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string';
+import { PeppolMessageLevelResponseDocumentResponse } from '#/schemas/peppol-message-level-response-document-response-schema';
+import { PeppolMessageLevelResponseParty } from '#/schemas/peppol-message-level-response-party-schema';
+import { opaque } from '#/schemas/utils/opaque';
+import { PeppolXsdTime } from '#/schemas/utils/peppol-xsd-time-schema';
+
+export class PeppolMessageLevelResponse extends opaque<PeppolMessageLevelResponse>()(
+  Schema.Struct({
+    /**
+     * @description Identifies the specification of content and rules that apply to the transaction.
+     *
+     * @default `urn:fdc:peppol.eu:poacc:trns:mlr:3`
+     *
+     * @summary Specification identification
+     *
+     * @name `cbc:CustomizationID`
+     *
+     * @cardinality 1..1
+     */
+    customizationId: Schema.String,
+    /**
+     * @description Identifies the BII profile or business process context in which the transaction appears.
+     *
+     * @remarks
+     *   Fixed value to `urn:fdc:peppol.eu:poacc:bis:mlr:3`
+     *
+     * @default `urn:fdc:peppol.eu:poacc:bis:mlr:3`
+     *
+     * @summary Business process type identifier
+     *
+     * @name `cbc:ProfileID`
+     */
+    profileId: Schema.Literal(MESSAGE_LEVEL_RESPONSE_PROFILE_ID),
+    /**
+     * @description A transaction instance must contain an identifier. The identifier enables positive referencing the transaction instance for various puropses
+     * including referencing between transactions that are part of the same process.
+     *
+     * @example
+     *   23;
+     *
+     * @summary Response identifier
+     *
+     * @name cbc:ID
+     */
+    id: Schema.String,
+    /**
+     * @description The date on which the transaction instance was issued.
+     *
+     * @example
+     *   2017 - 11 - 01;
+     *
+     * @summary Response issue date
+     *
+     * @format `YYYY-MM-DD`
+     *
+     * @name cbc:IssueDate
+     */
+    issueDate: PeppolIsoDateString,
+    /**
+     * @description The time at which the transaction instance was issued.
+     *
+     * @example
+     *   12:01:34
+     *
+     * @summary Response issue time
+     *
+     * @format `hh:mm:ss`
+     *
+     * @name cbc:IssueDate
+     */
+    issueTime: Schema.optional(PeppolXsdTime),
+    /**
+     * @description The party sending an electronic message level response message back to the sending party of the business document.
+     *
+     * @summary Sender information
+     */
+    senderParty: PeppolMessageLevelResponseParty,
+    /**
+     * @description The party, an electronic message level response was addressed to, and who is supposed to process the message level response. This is the same
+     * party as the sender of the business document.
+     *
+     * @summary Receiver information
+     */
+    receiverParty: PeppolMessageLevelResponseParty,
+    /**
+     * @description The document response is used to indicate the result of business document validation. The element
+     * `cac:DocumentResponse/cac:Response/cbc:ResponseCode` MUST contain the overall result code.
+     *
+     * @summary Document response
+     *
+     * @name `cac:DocumentResponse`
+     */
+    documentResponse: PeppolMessageLevelResponseDocumentResponse,
+  })
+) {}

package/src/schemas/utils/format-xsd-time.ts

@@ -0,0 +1,80 @@
+import { DateTime } from 'effect';
+
+/**
+ * @description Pads a number with leading zeros, preserving a leading `-` for negative values. Extracted from date-fns
+ * `pkgs/core/src/_lib/addLeadingZeros/index.ts`.
+ *
+ * @param value - The number to pad.
+ * @param targetLength - The total length the output should have.
+ *
+ * @returns The zero-padded string.
+ */
+const addLeadingZeros = (value: number, targetLength: number): string => {
+  const sign = value < 0 ? '-' : '';
+  return sign + Math.abs(value).toString().padStart(targetLength, '0');
+};
+
+/**
+ * @description The `HH`, `mm` and `ss` tokens extracted from the date-fns `lightFormatters` (`pkgs/core/src/_lib/format/lightFormatters/index.ts`). The date-fns
+ * implementation reads the local components of a `Date`; this port reads the UTC components because the caller hands it a `Date` whose UTC fields
+ * already hold the wall-clock time of the target time zone.
+ *
+ * @param date - A `Date` whose UTC fields hold the wall-clock time to format.
+ *
+ * @returns The zero-padded `HH` component.
+ */
+const formatHours = (date: Date): string => addLeadingZeros(date.getUTCHours(), 2);
+
+/**
+ * @description See {@link formatHours}. Formats the `mm` token.
+ *
+ * @param date - A `Date` whose UTC fields hold the wall-clock time to format.
+ *
+ * @returns The zero-padded `mm` component.
+ */
+const formatMinutes = (date: Date): string => addLeadingZeros(date.getUTCMinutes(), 2);
+
+/**
+ * @description See {@link formatHours}. Formats the `ss` token. Fractional seconds are dropped because XSD `time` values produced by this library carry second
+ * precision.
+ *
+ * @param date - A `Date` whose UTC fields hold the wall-clock time to format.
+ *
+ * @returns The zero-padded `ss` component.
+ */
+const formatSeconds = (date: Date): string => addLeadingZeros(date.getUTCSeconds(), 2);
+
+/**
+ * @description Formats a UTC offset as the ISO-8601 `XXX` token (`+HH:MM` / `-HH:MM`). The digit handling is extracted from date-fns `formatTimezone`
+ * (`pkgs/core/src/_lib/format/formatters/index.ts`) with two deliberate differences:
+ *
+ * 1. The offset is expressed in the standard direction (positive means east of UTC) instead of JavaScript's inverted `Date#getTimezoneOffset` sign.
+ * 2. A zero offset returns an empty string. date-fns renders it as `Z`; XSD `time` wants the time zone to be optional, so UTC produces no offset at all.
+ *
+ * @param offsetInMinutes - The offset east of UTC in minutes (for example `+05:30` is `330`).
+ *
+ * @returns The formatted offset, or an empty string for UTC.
+ */
+export const formatTimeZoneOffset = (offsetInMinutes: number): string => {
+  if (offsetInMinutes === 0) return '';
+  const sign = offsetInMinutes > 0 ? '+' : '-';
+  const absoluteOffset = Math.abs(offsetInMinutes);
+  const hours = addLeadingZeros(Math.trunc(absoluteOffset / 60), 2);
+  const minutes = addLeadingZeros(absoluteOffset % 60, 2);
+  return `${sign}${hours}:${minutes}`;
+};
+
+/**
+ * @description Formats a `DateTime` as an XSD `time` lexical value: `HH:mm:ss` followed by an optional `±HH:MM` offset. The offset is omitted for UTC, so a UTC
+ * value encodes as bare `HH:mm:ss` while a zoned value encodes as `HH:mm:ss±HH:MM`. Fractional seconds are intentionally dropped to match the second
+ * precision the schema round-trips.
+ *
+ * @param date - The `DateTime` to format. It is rendered in its own time zone, not normalised to UTC.
+ *
+ * @returns The XSD `time` string.
+ */
+export const formatXsdTime = (date: DateTime.DateTime): string => {
+  const wallClock = DateTime.toDate(date);
+  const offsetInMinutes = (wallClock.getTime() - DateTime.toEpochMillis(date)) / (60 * 1000);
+  return `${formatHours(wallClock)}:${formatMinutes(wallClock)}:${formatSeconds(wallClock)}${formatTimeZoneOffset(offsetInMinutes)}`;
+};

package/src/{effect → schemas}/utils/index.ts

@@ -7,4 +7,4 @@ export * from './is-valid-invoice-type-code';
 export * from './is-valid-process';
 export * from './quantity-unit-code-to-intl-unit';
 export * from './peppol-vat-regex-schema';
-export * from './peppol-xsd-time-schema';
+export { PeppolXsdTime } from './peppol-xsd-time-schema';