@shopickup/adapters-foxpost 0.0.1

package/dist/types/generated.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Generated types for Foxpost API
+ * This file was generated from hu-foxpost.openapi.yaml
+ *
+ * NOTE: This is a manual stub. In production, use openapi-typescript to generate
+ * these types automatically:
+ * npx openapi-typescript ../../carrier-docs/hu-foxpost/hu-foxpost.openapi.yaml --output ./src/types/generated.ts
+ */
+/**
+ * Request to create a parcel
+ */
+export interface CreateParcelRequest {
+    /** Name of recipient (required) */
+    recipientName: string;
+    /** Phone of recipient (required) */
+    recipientPhone: string;
+    /** Email of recipient (required) */
+    recipientEmail: string;
+    /** Size of the parcel: xs, s, m, l, xl */
+    size?: "xs" | "s" | "m" | "l" | "xl";
+    /** Country code (defaults to HU) */
+    recipientCountry?: string;
+    /** City of recipient (required for HD - home delivery) */
+    recipientCity?: string;
+    /** Postal code (required for HD) */
+    recipientZip?: string;
+    /** Street address (required for HD) */
+    recipientAddress?: string;
+    /** Cash on delivery amount */
+    cod?: number;
+    /** Delivery note for courier */
+    deliveryNote?: string;
+    /** Comment about parcel contents */
+    comment?: string;
+    /** Whether Foxpost will print the label */
+    label?: boolean;
+    /** Whether parcel is fragile */
+    fragile?: boolean;
+    /** Unique barcode (if customer provides one) */
+    uniqueBarcode?: string;
+    /** Reference code for tracking */
+    refCode?: string;
+    /** APM (automated parcel machine) ID for redirect */
+    destination?: string;
+}
+/**
+ * Field validation error
+ */
+export interface FieldError {
+    /** Field name that has error */
+    field: string;
+    /** Validation error message */
+    message: string;
+}
+/**
+ * Response from parcel creation
+ */
+export interface CreateResponse {
+    /** Whether all parcels were created successfully */
+    valid: boolean;
+    /** List of created parcels */
+    parcels: Package[];
+}
+/**
+ * Created parcel details
+ */
+export interface Package {
+    /** Barcode assigned to this parcel */
+    barcode?: string;
+    /** Reference code */
+    refCode?: string;
+    /** Unique barcode if provided */
+    uniqueBarcode?: string;
+    /** Validation errors if any */
+    errors?: FieldError[];
+}
+/**
+ * Request to get batch tracking
+ */
+export interface BatchTrackRequest {
+    barcodes: string[];
+}
+/**
+ * Tracking status response
+ */
+export interface Statuses {
+    /** Barcode of the parcel */
+    barcode: string;
+    /** When parcel was created */
+    createdAt: string;
+    /** List of tracking events */
+    statuses: TrackDTO[];
+}
+/**
+ * Single tracking event
+ */
+export interface TrackDTO {
+    /** Track event ID */
+    trackId?: number;
+    /** Status code */
+    status?: string;
+    /** Human-readable status name */
+    longName?: string;
+    /** When this status occurred */
+    statusDate?: string;
+    /** Location information */
+    location?: string;
+}
+/**
+ * Tracking response for single parcel (NEW /api/tracking/{barcode} endpoint)
+ * Based on Foxpost API v1 documentation section 6.3
+ */
+export interface TrackingResponse {
+    /** Tracking number */
+    trackingNumber?: string;
+    /** The queried parcel's clFoxId */
+    clFox: string;
+    /** Expected delivery date (yyyy-mm-dd) */
+    estimatedDelivery: string | null;
+    /** Parcel type: "NORMAL", "RE", "XRE", "IRE", "C2B" */
+    parcelType: "NORMAL" | "RE" | "XRE" | "IRE" | "C2B";
+    /** Related (previous) parcel clFox for returns (RE, XRE, IRE only) */
+    relatedParcel: string | null;
+    /** Delivery type: "APM", "HD", "COLLECT" */
+    sendType: "APM" | "HD" | "COLLECT";
+    /** Array of tracking traces in reverse chronological order (latest first) */
+    traces: TraceDTO[];
+}
+/**
+ * Single tracking trace/event from the new tracking endpoint
+ */
+export interface TraceDTO {
+    /** Long human-readable status name */
+    longName?: string;
+    /** Short status code/name */
+    shortName?: string;
+    /** Status code */
+    status?: string;
+    /** When this status occurred */
+    statusDate?: string;
+    /** Status station ID reference on foxpost.hu */
+    statusStatidionId?: string;
+}
+/**
+ * Tracking response for single parcel (LEGACY /tracking endpoint - keep for backwards compatibility)
+ */
+export interface Tracking {
+    /** Barcode of the parcel */
+    barcode: string;
+    /** When parcel was created */
+    createdAt: string;
+    /** List of tracking events */
+    statuses: TrackDTO[];
+}
+/**
+ * Label information
+ */
+export interface LabelInfo {
+    /** Barcode */
+    barcode: string;
+    /** Whether label can be generated */
+    canGenerate?: boolean;
+    /** PDF content if available */
+    pdf?: string;
+}
+/**
+ * API Error response
+ */
+export interface ApiError {
+    /** Timestamp of error */
+    timestamp?: string;
+    /** Error code */
+    error?: string;
+    /** HTTP status */
+    status?: number;
+}
+//# sourceMappingURL=generated.d.ts.map

package/dist/types/generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../src/types/generated.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,aAAa,EAAE,MAAM,CAAC;IAEtB,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;IAEvB,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;IAEvB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC;IAErC,oCAAoC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,uCAAuC;IACvC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,gCAAgC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IAEd,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,KAAK,EAAE,OAAO,CAAC;IAEf,8BAA8B;IAC9B,OAAO,EAAE,OAAO,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,iCAAiC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAEhB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAElB,8BAA8B;IAC9B,QAAQ,EAAE,QAAQ,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sBAAsB;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IAEd,0CAA0C;IAC1C,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjC,uDAAuD;IACvD,UAAU,EAAE,QAAQ,GAAG,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;IAEpD,sEAAsE;IACtE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,4CAA4C;IAC5C,QAAQ,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;IAEnC,6EAA6E;IAC7E,MAAM,EAAE,QAAQ,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAEhB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAElB,8BAA8B;IAC9B,QAAQ,EAAE,QAAQ,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,cAAc;IACd,OAAO,EAAE,MAAM,CAAC;IAEhB,qCAAqC;IACrC,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,+BAA+B;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/types/generated.js

@@ -0,0 +1,9 @@
+/**
+ * Generated types for Foxpost API
+ * This file was generated from hu-foxpost.openapi.yaml
+ *
+ * NOTE: This is a manual stub. In production, use openapi-typescript to generate
+ * these types automatically:
+ * npx openapi-typescript ../../carrier-docs/hu-foxpost/hu-foxpost.openapi.yaml --output ./src/types/generated.ts
+ */
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generated types from OpenAPI will be placed here
+ * To regenerate: npm run codegen
+ */
+export * from './generated.js';
+export type { CreateParcelRequest, CreateResponse, TrackDTO, Tracking } from './generated.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,gBAAgB,CAAC;AAG/B,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,6 @@
+/**
+ * Generated types from OpenAPI will be placed here
+ * To regenerate: npm run codegen
+ */
+// Export generated types
+export * from './generated.js';

package/dist/utils/httpUtils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Foxpost HTTP Client Utilities
+ * Thin utilities for building Foxpost API requests
+ */
+import type { FoxpostCredentials } from '../validation.js';
+/**
+ * Build standard Foxpost auth headers
+ * Requires both Basic auth (username:password) and API key
+ * Uses capitalized "Api-key" header (Foxpost recommended format)
+ */
+export declare function buildFoxpostHeaders(credentials: FoxpostCredentials): Record<string, string>;
+/**
+ * Build Foxpost headers for binary responses (e.g., PDF)
+ * Uses capitalized "Api-key" header (Foxpost recommended format)
+ * Sets Accept-Encoding to application/pdf so Foxpost returns JSON on errors
+ */
+export declare function buildFoxpostBinaryHeaders(credentials: FoxpostCredentials): Record<string, string>;
+//# sourceMappingURL=httpUtils.d.ts.map

package/dist/utils/httpUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpUtils.d.ts","sourceRoot":"","sources":["../../src/utils/httpUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU3F;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWjG"}

package/dist/utils/httpUtils.js

@@ -0,0 +1,33 @@
+/**
+ * Foxpost HTTP Client Utilities
+ * Thin utilities for building Foxpost API requests
+ */
+/**
+ * Build standard Foxpost auth headers
+ * Requires both Basic auth (username:password) and API key
+ * Uses capitalized "Api-key" header (Foxpost recommended format)
+ */
+export function buildFoxpostHeaders(credentials) {
+    const { apiKey, basicUsername, basicPassword } = credentials;
+    const basicAuth = Buffer.from(`${basicUsername}:${basicPassword}`).toString("base64");
+    return {
+        "Content-Type": "application/json",
+        "Authorization": `Basic ${basicAuth}`,
+        ...(apiKey && { "Api-key": apiKey }),
+    };
+}
+/**
+ * Build Foxpost headers for binary responses (e.g., PDF)
+ * Uses capitalized "Api-key" header (Foxpost recommended format)
+ * Sets Accept-Encoding to application/pdf so Foxpost returns JSON on errors
+ */
+export function buildFoxpostBinaryHeaders(credentials) {
+    const { apiKey, basicUsername, basicPassword } = credentials;
+    const basicAuth = Buffer.from(`${basicUsername}:${basicPassword}`).toString("base64");
+    return {
+        "Accept-Encoding": "application/pdf",
+        "Content-Type": "application/json",
+        "Authorization": `Basic ${basicAuth}`,
+        ...(apiKey && { "Api-key": apiKey }),
+    };
+}

package/dist/utils/resolveBaseUrl.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Factory that creates a resolver function bound to production and test base URLs.
+ *
+ * This removes duplication of base URL strings across capability files while keeping
+ * per-call decision logic explicit and testable.
+ *
+ * Usage:
+ *   const resolveBaseUrl = createResolveBaseUrl(prodUrl, testUrl);
+ *   const url = resolveBaseUrl(req.options); // returns test or prod based on useTestApi flag
+ *
+ * @param prodBaseUrl Production API base URL
+ * @param testBaseUrl Test/sandbox API base URL
+ * @returns A pure resolver function that accepts request options and returns the appropriate URL
+ */
+export declare function createResolveBaseUrl(prodBaseUrl: string, testBaseUrl: string): (opts?: {
+    useTestApi?: boolean;
+}) => string;
+/**
+ * Type definition for the resolver function returned by createResolveBaseUrl.
+ * Useful for typing capability function parameters.
+ */
+export type ResolveBaseUrl = ReturnType<typeof createResolveBaseUrl>;
+//# sourceMappingURL=resolveBaseUrl.d.ts.map

package/dist/utils/resolveBaseUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveBaseUrl.d.ts","sourceRoot":"","sources":["../../src/utils/resolveBaseUrl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,IACnE,OAAO;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,KAAG,MAAM,CAGjD;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/utils/resolveBaseUrl.js

@@ -0,0 +1,19 @@
+/**
+ * Factory that creates a resolver function bound to production and test base URLs.
+ *
+ * This removes duplication of base URL strings across capability files while keeping
+ * per-call decision logic explicit and testable.
+ *
+ * Usage:
+ *   const resolveBaseUrl = createResolveBaseUrl(prodUrl, testUrl);
+ *   const url = resolveBaseUrl(req.options); // returns test or prod based on useTestApi flag
+ *
+ * @param prodBaseUrl Production API base URL
+ * @param testBaseUrl Test/sandbox API base URL
+ * @returns A pure resolver function that accepts request options and returns the appropriate URL
+ */
+export function createResolveBaseUrl(prodBaseUrl, testBaseUrl) {
+    return (opts) => {
+        return opts?.useTestApi ? testBaseUrl : prodBaseUrl;
+    };
+}