@deenruv/inpost 1.0.0

package/src/api/organizations/index.ts

@@ -0,0 +1,51 @@
+import {
+  FetchFn,
+  endpoint,
+  get,
+  jsonResponse,
+  is2xx,
+} from "../../middleware/index.js";
+import { Shipment } from "../../models/index.js";
+import { isArray } from "../../validators/array.js";
+import { isNumber } from "../../validators/number.js";
+import { isObject } from "../../validators/object.js";
+import { isOrganization } from "../../validators/organization.js";
+import { isShipment } from "../../validators/is_shipment.js";
+import { isString } from "../../validators/string.js";
+import { Shipments } from "./shipments.js";
+
+export interface ShipmentListResponse {
+  href: string;
+  count: number;
+  page: number;
+  per_page: number;
+  items: Shipment[];
+}
+
+const mustShipmentList = (v: ShipmentListResponse) =>
+  isString(v.href) &&
+  isNumber(v.count) &&
+  isNumber(v.page) &&
+  isNumber(v.per_page) &&
+  isArray(isShipment)(v.items);
+
+export const isShipmentList = (v: unknown): v is ShipmentListResponse =>
+  isObject(v) && mustShipmentList(v as ShipmentListResponse);
+
+export class Organization {
+  constructor(
+    private apiBase: URL,
+    private fetchFn: FetchFn,
+  ) {}
+
+  async fetch() {
+    const res = await jsonResponse(isOrganization)(get(is2xx(this.fetchFn)))(
+      this.apiBase,
+    );
+    return res.jsonResponse;
+  }
+
+  shipments() {
+    return new Shipments(this.apiBase, endpoint("shipments")(this.fetchFn));
+  }
+}

package/src/api/organizations/shipments.ts

@@ -0,0 +1,53 @@
+import {
+  FetchFn,
+  get,
+  jsonRequest,
+  jsonResponse,
+  post,
+  is2xx,
+} from '../../middleware/index.js';
+import { Shipment } from '../../models/index.js';
+import { isArray } from '../../validators/array.js';
+import { isNumber } from '../../validators/number.js';
+import { isObject } from '../../validators/object.js';
+import { isShipment } from '../../validators/is_shipment.js';
+import { isString } from '../../validators/string.js';
+
+export interface ShipmentListResponse {
+  href: string;
+  count: number;
+  page: number;
+  per_page: number;
+  items: Shipment[];
+}
+
+const mustShipmentList = (v: ShipmentListResponse) =>
+  isString(v.href) &&
+  isNumber(v.count) &&
+  isNumber(v.page) &&
+  isNumber(v.per_page) &&
+  isArray(isShipment)(v.items);
+
+export const isShipmentList = (v: unknown): v is ShipmentListResponse =>
+  isObject(v) && mustShipmentList(v as ShipmentListResponse);
+
+export class Shipments {
+  constructor(
+    private apiBase: URL,
+    private fetchFn: FetchFn,
+  ) {}
+
+  async list() {
+    const res = await jsonResponse(isShipmentList)(get(is2xx(this.fetchFn)))(
+      this.apiBase,
+    );
+    return res.jsonResponse;
+  }
+
+  async create(data: Shipment): Promise<Shipment> {
+    const res = await jsonResponse(isShipment)(
+      post(jsonRequest(data)(is2xx(this.fetchFn))),
+    )(this.apiBase);
+    return res.jsonResponse;
+  }
+}

package/src/api/organizations.ts

@@ -0,0 +1,44 @@
+import { FetchFn, endpoint, get, jsonResponse, is2xx } from '../middleware/index.js';
+import { Organization } from '../models/index.js';
+import { isArray } from '../validators/array.js';
+import { isNumber } from '../validators/number.js';
+import { isObject } from '../validators/object.js';
+import { isOrganization } from '../validators/organization.js';
+import { isString } from '../validators/string.js';
+import { Organization as OrganizationAPI } from './organizations/index.js';
+
+export interface OrganizationListResponse {
+  href: string;
+  count: number;
+  page: number;
+  per_page: number;
+  items: Organization[];
+}
+
+const mustOrganizationList = (v: OrganizationListResponse) =>
+  isString(v.href) &&
+  isNumber(v.count) &&
+  isNumber(v.page) &&
+  isNumber(v.per_page) &&
+  isArray(isOrganization)(v.items);
+
+export const isOrganizationList = (v: unknown): v is OrganizationListResponse =>
+  isObject(v) && mustOrganizationList(v as OrganizationListResponse);
+
+export class Organizations {
+  constructor(
+    private apiBase: URL,
+    private fetch: FetchFn,
+  ) {}
+
+  async list() {
+    const res = await jsonResponse(isOrganizationList)(get(is2xx(this.fetch)))(
+      this.apiBase,
+    );
+    return res.jsonResponse;
+  }
+
+  get(id: number) {
+    return new OrganizationAPI(this.apiBase, endpoint(`${id}`)(this.fetch));
+  }
+}

package/src/api/shipments/index.ts

@@ -0,0 +1,44 @@
+import {
+  endpoint,
+  is2xx,
+  values,
+  FetchFn,
+  get,
+  jsonResponse,
+  jsonRequest,
+  post,
+} from '../../middleware/index.js';
+import { isShipment } from '../../validators/is_shipment.js';
+
+export class Shipment {
+  constructor(
+    private apiBase: URL,
+    private fetchFn: FetchFn,
+  ) {}
+
+  async fetch() {
+    const res = await jsonResponse(isShipment)(get(is2xx(this.fetchFn)))(
+      this.apiBase,
+    );
+    return res.jsonResponse;
+  }
+
+  async label(
+    args: {
+      format?: 'Pdf' | 'Zpl' | 'Epl';
+      type?: 'normal' | 'A6' | 'dpi300';
+    } = {},
+  ) {
+    const res = await endpoint('label')(values(args)(get(is2xx(this.fetchFn))))(
+      this.apiBase,
+    );
+    return res.body;
+  }
+
+  async buy(body: { offer_id: number }) {
+    const res = await jsonResponse(isShipment)(
+      endpoint('buy')(jsonRequest(body)(post(is2xx(this.fetchFn)))),
+    )(this.apiBase);
+    return res.jsonResponse;
+  }
+}

package/src/api/shipments.ts

@@ -0,0 +1,59 @@
+import {
+  FetchFn,
+  endpoint,
+  get,
+  jsonRequest,
+  jsonResponse,
+  post,
+  is2xx,
+} from '../middleware/index.js';
+import { Shipment } from '../models/index.js';
+import { isArray } from '../validators/array.js';
+import { isNumber } from '../validators/number.js';
+import { isObject } from '../validators/object.js';
+import { isShipment } from '../validators/is_shipment.js';
+import { isString } from '../validators/string.js';
+import { Shipment as ShipmentAPI } from './shipments/index.js';
+
+export interface ShipmentListResponse {
+  href: string;
+  count: number;
+  page: number;
+  per_page: number;
+  items: Shipment[];
+}
+
+const mustShipmentList = (v: ShipmentListResponse) =>
+  isString(v.href) &&
+  isNumber(v.count) &&
+  isNumber(v.page) &&
+  isNumber(v.per_page) &&
+  isArray(isShipment)(v.items);
+
+export const isShipmentList = (v: unknown): v is ShipmentListResponse =>
+  isObject(v) && mustShipmentList(v as ShipmentListResponse);
+
+export class Shipments {
+  constructor(
+    private apiBase: URL,
+    private fetchFn: FetchFn,
+  ) {}
+
+  async list() {
+    const res = await jsonResponse(isShipmentList)(get(is2xx(this.fetchFn)))(
+      this.apiBase,
+    );
+    return res.jsonResponse;
+  }
+
+  async create(data: Shipment): Promise<Shipment> {
+    const res = await jsonResponse(isShipment)(
+      post(jsonRequest(data)(is2xx(this.fetchFn))),
+    )(this.apiBase);
+    return res.jsonResponse;
+  }
+
+  get(id: number) {
+    return new ShipmentAPI(this.apiBase, endpoint(`${id}`)(this.fetchFn));
+  }
+}

package/src/error.ts

@@ -0,0 +1,10 @@
+export class InvalidBody extends Error {}
+
+export class InvalidResponseStatus extends Error {
+  constructor(
+    msg: string,
+    public res: Response,
+  ) {
+    super(msg);
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,127 @@
+import { describe, it } from "node:test";
+import { doesNotReject, notEqual } from "node:assert";
+import { Client, CountryCode } from "./index.js";
+import { createWriteStream } from "fs";
+import { tmpdir } from "node:os";
+import { mkdtemp, rm } from "fs/promises";
+import { join } from "node:path";
+import { Writable } from "node:stream";
+
+const {
+  INPOST_HOST: host = "sandbox-api-shipx-pl.easypack24.net",
+  INPOST_API_KEY: apiKey,
+} = process.env as {
+  INPOST_HOST: string;
+  INPOST_API_KEY: string;
+};
+
+describe("inpost client tests", { skip: !apiKey }, () => {
+  const client = new Client({ host, apiKey });
+  it("lists organizations", () => doesNotReject(client.organizations().list()));
+  it("fetches organization", () =>
+    doesNotReject(
+      client
+        .organizations()
+        .list()
+        .then((orgs) => client.organizations().get(orgs.items[0].id).fetch()),
+    ));
+  it("fetches shipments", () =>
+    doesNotReject(
+      client
+        .organizations()
+        .list()
+        .then((orgs) =>
+          client.organizations().get(orgs.items[0].id).shipments().list(),
+        ),
+    ));
+  it("test shipment flow", () =>
+    doesNotReject(async () => {
+      const orgs = await client.organizations().list();
+      const org = orgs.items[0];
+      // is not falsy
+      notEqual(!!org, false);
+      let shipment = await client
+        .organizations()
+        .get(org.id)
+        .shipments()
+        .create({
+          receiver: {
+            first_name: "Test",
+            last_name: "Test",
+            email: "email@example.org",
+            phone: "321321321",
+            address: {
+              street: "Czerniakowska",
+              building_number: "87A",
+              city: "Warszawa",
+              post_code: "00-718",
+              country_code: CountryCode.pl,
+            },
+          },
+          sender: {
+            company_name: "Company_name",
+            first_name: "Test",
+            last_name: "Test",
+            email: "email@example.com",
+            phone: "888000000",
+            address: {
+              line1: "Cybernetyki 10",
+              city: "Warszawa",
+              post_code: "02-677",
+              country_code: CountryCode.pl,
+            },
+          },
+          parcels: [{ template: "small" }],
+          service: "inpost_locker_standard",
+          custom_attributes: {
+            target_point: "KRA010",
+          },
+        });
+
+      while (!shipment.status || shipment.status === "created") {
+        console.log("Waiting for shipment to be created...");
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        shipment = await client.shipments().get(shipment.id).fetch();
+      }
+
+      shipment = await client
+        .shipments()
+        .get(shipment.id)
+        .buy({ offer_id: shipment.offers[0].id });
+
+      let found = shipment.transactions?.find(
+        (t) => t.status === "success" && t.offer_id === shipment.offers?.[0].id,
+      );
+
+      while (!found) {
+        console.log("Waiting for transaction to succeed...");
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        shipment = await client.shipments().get(shipment.id).fetch();
+        found = shipment.transactions?.find((t) => t.status === "success");
+        if (!found) {
+          await client
+            .shipments()
+            .get(shipment.id)
+            .buy({ offer_id: shipment.offers[0].id });
+        }
+      }
+
+      while (
+        !shipment.status ||
+        shipment.status === "created" ||
+        shipment.status === "offer_selected"
+      ) {
+        console.log("Waiting for shipment to be ready...");
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        shipment = await client.shipments().get(shipment.id).fetch();
+      }
+      const tmp = await mkdtemp(join(tmpdir(), "test-inpost-label"));
+      const label = await client.shipments().get(shipment.id).label();
+      await label.pipeTo(
+        Writable.toWeb(
+          createWriteStream(join(tmp, "label.pdf")),
+        ) as WritableStream<Uint8Array>,
+      );
+      await rm(tmp, { force: true, recursive: true });
+    }));
+});

package/src/index.ts

@@ -0,0 +1,33 @@
+import { Organizations } from "./api/organizations.js";
+import { Shipments } from "./api/shipments.js";
+import { Middleware, auth, endpoint } from "./middleware/index.js";
+export class Client {
+  private auth: Middleware;
+  private base: URL;
+  constructor(
+    private opts: {
+      host: string;
+      version?: string;
+      apiKey: string;
+    },
+  ) {
+    this.auth = auth(this.opts.apiKey);
+    this.base = new URL(`https://${this.opts.host}`);
+  }
+  private doRequest() {
+    return (info: string | URL, init?: RequestInit) => {
+      return endpoint(this.opts.version || "v1")(this.auth(fetch))(info, init);
+    };
+  }
+  organizations() {
+    return new Organizations(
+      this.base,
+      endpoint("organizations")(this.doRequest()),
+    );
+  }
+
+  shipments() {
+    return new Shipments(this.base, endpoint("shipments")(this.doRequest()));
+  }
+}
+export * from "./models/index.js";

package/src/middleware/auth.ts

@@ -0,0 +1,12 @@
+import { Middleware } from './middleware.js';
+export const auth =
+  (token: string): Middleware =>
+  (next) =>
+  (info, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set('authorization', `Bearer ${token}`);
+    return next(info, {
+      ...init,
+      headers,
+    });
+  };

package/src/middleware/endpoint.ts

@@ -0,0 +1,12 @@
+import { Middleware } from './middleware.js';
+const buildEndpoint = (url: string | URL, endpoint: string) => {
+  url = new URL(url);
+  url.pathname = `${endpoint.replace(/\/+$/, '')}/${url.pathname.replace(/^\/+/, '')}`;
+  return url;
+};
+
+export const endpoint =
+  (endpoint: string): Middleware =>
+  (next) =>
+  (info, init) =>
+    next(buildEndpoint(info, endpoint), init);

package/src/middleware/expect_200.ts

@@ -0,0 +1,28 @@
+import { FetchFn, Middleware } from "./middleware.js";
+import { InvalidResponseStatus } from "../error.js";
+
+export const is2xx: Middleware =
+  <U>(next: FetchFn<U>) =>
+  async (info, init) => {
+    const res = await next(info, init);
+    if (res.status < 200 || res.status > 299) {
+      if ((process.env.LOG_LEVEL || "").toLowerCase() === "debug") {
+        console.log(await res.text());
+      }
+      // Let user know message from the response if available
+      let error: { message: string; details: string };
+      try {
+        error = await res.json();
+      } catch {
+        error = {
+          message: "Unknown error",
+          details: "No additional details available",
+        };
+      }
+      throw new InvalidResponseStatus(
+        `${error.message}: ${error.details}, (status: ${res.status})`,
+        res,
+      );
+    }
+    return res;
+  };

package/src/middleware/get.ts

@@ -0,0 +1,6 @@
+import { Middleware } from './middleware.js';
+export const get: Middleware = (next) => (info, init) =>
+  next(info, {
+    ...init,
+    method: 'GET',
+  });

package/src/middleware/index.ts

@@ -0,0 +1,9 @@
+export * from './middleware.js';
+export * from './get.js';
+export * from './post.js';
+export * from './endpoint.js';
+export * from './json_request.js';
+export * from './json_response.js';
+export * from './auth.js';
+export * from './expect_200.js';
+export * from './values.js';

package/src/middleware/json_request.ts

@@ -0,0 +1,15 @@
+import { Middleware } from './middleware.js';
+
+export const jsonRequest =
+  (rawBody: unknown): Middleware =>
+  (next) =>
+  async (info, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set('content-type', `application/json`);
+    const body = JSON.stringify(rawBody);
+    return next(info, {
+      ...init,
+      headers,
+      body,
+    });
+  };

package/src/middleware/json_response.ts

@@ -0,0 +1,18 @@
+import { FetchFn, Middleware } from './middleware.js';
+import { InvalidBody } from '../error.js';
+export type JSONResponse<T> = {
+  jsonResponse: T;
+};
+export const jsonResponse =
+  <T>(validate: (v: unknown) => v is T): Middleware<JSONResponse<T>> =>
+  <U>(next: FetchFn<U>) =>
+  async (info, init) => {
+    const res = await next(info, init);
+    type ResponseType = Response & JSONResponse<T> & U;
+    const data = await res.json();
+    if (!validate(data)) {
+      throw new InvalidBody('invalid response body');
+    }
+    (res as ResponseType).jsonResponse = data;
+    return res as ResponseType;
+  };

package/src/middleware/middleware.ts

@@ -0,0 +1,7 @@
+export type FetchFn<T = unknown> = (
+  info: string | URL,
+  init?: RequestInit,
+) => Promise<T & Response>;
+export interface Middleware<T = unknown> {
+  <U = unknown>(next: FetchFn<U>): FetchFn<T & U>;
+}

package/src/middleware/post.ts

@@ -0,0 +1,7 @@
+import { Middleware } from './middleware.js';
+
+export const post: Middleware = (next) => (info, init) =>
+  next(info, {
+    ...init,
+    method: 'POST',
+  });

package/src/middleware/values.ts

@@ -0,0 +1,23 @@
+import { Middleware } from "./middleware.js";
+
+type Values =
+  | string
+  | [string, string][]
+  | Record<string, string>
+  | URLSearchParams;
+
+const buildValues = (url: string | URL, values: Values) => {
+  url = new URL(url);
+  const params = new URLSearchParams(url.searchParams);
+  for (const [key, value] of new URLSearchParams(values)) {
+    params.set(key, value);
+  }
+  url.search = params.toString();
+  return url;
+};
+
+export const values =
+  (values: Values): Middleware =>
+  (next) =>
+  (info, init) =>
+    next(buildValues(info, values), init);

package/src/models/address.ts

@@ -0,0 +1,16 @@
+import { CountryCode } from './country_code.js';
+export type Address = {
+  id?: number;
+  city: string;
+  country_code: CountryCode;
+  post_code: string;
+} & (
+  | {
+      line1: string;
+      line2?: string;
+    }
+  | {
+      street: string;
+      building_number: string;
+    }
+);

package/src/models/carrier.ts

@@ -0,0 +1 @@
+export type Carrier = 'inpost_locker' | 'inpost_letter' | 'inpost_courier';

package/src/models/country_code.ts

@@ -0,0 +1,4 @@
+export const enum CountryCode {
+  pl = 'PL',
+  en = 'EN',
+}

package/src/models/currency_code.ts

@@ -0,0 +1,3 @@
+export const enum CurrencyCode {
+  PLN = 'PLN',
+}

package/src/models/index.ts

@@ -0,0 +1,11 @@
+export * from "./address.js";
+export * from "./carrier.js";
+export * from "./country_code.js";
+export * from "./currency_code.js";
+export * from "./money.js";
+export * from "./offer.js";
+export * from "./organization.js";
+export * from "./parcel.js";
+export * from "./person.js";
+export * from "./shipment.js";
+export * from "./service.js";

package/src/models/money.ts

@@ -0,0 +1,5 @@
+import { CurrencyCode } from './currency_code.js';
+export interface Money {
+  amount: number;
+  currency: CurrencyCode;
+}

package/src/models/offer.ts

@@ -0,0 +1,4 @@
+export interface Offer {
+  id: number;
+  status: string;
+}

package/src/models/organization.ts

@@ -0,0 +1,19 @@
+import { Address } from './address.js';
+import { Carrier } from './carrier.js';
+import { Person } from './person.js';
+import { Service } from './service.js';
+export interface Organization {
+  address: Address;
+  bank_account_number?: string;
+  carriers: Carrier[];
+  contact_person?: Person;
+  created_at: string;
+  href: string;
+  id: number;
+  invoice_address?: Address;
+  name: string;
+  owner_id: number;
+  services: Service[];
+  tax_id: string;
+  updated_at: string;
+}