@myparcel-dev/sdk 5.0.0

package/lib/model/client/AbstractClient.d.ts

@@ -0,0 +1,89 @@
+import { Interceptors } from './middleware/Interceptors';
+import { RequestHeader, RequestHeaders, ResponseWrapper } from '../../types/request.types';
+import { WithRequired } from '../../types';
+import { AbstractEndpoint } from '../endpoint/AbstractEndpoint';
+import { ClientConfig, ClientOptions, ClientRequest, EndpointPath, EndpointResponse, EndpointResponseBody, PaginatedEndpointResponse, Options, OptionsWithBody, OptionsWithoutBody } from './AbstractClient.types';
+
+export declare const BASE_URL = "https://api.myparcel.nl";
+export declare abstract class AbstractClient {
+    /**
+     * Interceptors for request and response.
+     *
+     * @protected
+     */
+    interceptors: {
+        request: Interceptors<OptionsWithBody<AbstractEndpoint> | OptionsWithoutBody<AbstractEndpoint>>;
+        response: Interceptors<ResponseWrapper<EndpointResponseBody<AbstractEndpoint>>>;
+    };
+    /**
+     * Executes the request. Should return a promise containing the response json as object.
+     */
+    protected abstract request: ClientRequest;
+    /**
+     * Base URL to make requests to.
+     *
+     * @protected
+     */
+    protected baseUrl: string;
+    /**
+     * Headers to use with requests.
+     *
+     * @protected
+     */
+    protected headers: RequestHeaders;
+    /**
+     * @protected
+     */
+    protected parameters: Record<string, string>;
+    /**
+     * Additional client specific options.
+     *
+     * @protected
+     */
+    protected options: ClientOptions;
+    /**
+     * Array of headers that are required. Client will throw an error if any are missing.
+     *
+     * @private
+     */
+    private _requiredHeaders;
+    protected constructor(config?: ClientConfig);
+    get requiredHeaders(): (RequestHeader | string)[];
+    set requiredHeaders(value: (RequestHeader | string)[]);
+    /**
+     * Prepare and execute the final request and handle the response.
+     */
+    doRequest<E extends AbstractEndpoint>(endpoint: E, options: Options<E>): Promise<EndpointResponse<E>>;
+    getResponseBody<E extends AbstractEndpoint>(endpoint: E, response: EndpointResponse<E>): EndpointResponse<E> | PaginatedEndpointResponse<E>;
+    /**
+     * Gets default and custom headers.
+     *
+     * @protected
+     */
+    protected getHeaders(): RequestHeaders;
+    /**
+     * Uses the base url, endpoint and options to create the final request url.
+     *
+     * @protected
+     */
+    protected createUrl<E extends AbstractEndpoint>(endpoint: E, options: Options<E>): string;
+    /**
+     * Replace path variables in an url path. Deletes optional parameters if
+     * they're not passed.
+     *
+     * @protected
+     */
+    protected substitutePath<E extends AbstractEndpoint>(urlPath: string, pathVariables?: EndpointPath<E>): string;
+    /**
+     * Validates headers passed in options.
+     *
+     * @protected
+     */
+    protected validateHeaders<E extends AbstractEndpoint>(endpoint: E, options: WithRequired<Options<E>, 'headers'>): void;
+    /**
+     * Executes transformations on options before request.
+     *
+     * @protected
+     */
+    protected normalizeOptions<E extends AbstractEndpoint>(endpoint: E, options: Options<E>): WithRequired<Options<E>, 'headers'>;
+}

package/lib/model/client/AbstractClient.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/model/client/AbstractClient.types.d.ts

@@ -0,0 +1,55 @@
+import { Interceptors } from './middleware/Interceptors';
+import { RequestHeaders, ResponseWrapper } from '../../types/request.types';
+import { AbstractEndpoint } from '../endpoint/AbstractEndpoint';
+import { AbstractClient } from './AbstractClient';
+
+interface ClientPlugin {
+    getClient?: () => void;
+    init?: (client: AbstractClient) => void;
+    transformRequest?: () => void;
+    transformResponse?: <Endpoint extends AbstractEndpoint>(response: ResponseWrapper<EndpointResponseBody<Endpoint>>) => ResponseWrapper<EndpointResponseBody<Endpoint>>;
+}
+type PluginConstructor = (client: AbstractClient) => ClientPlugin;
+export interface ClientConfig {
+    baseUrl?: string;
+    headers?: RequestHeaders;
+    parameters?: Record<string, string>;
+    plugins?: PluginConstructor[];
+    options?: ClientOptions;
+    interceptors?: {
+        request: Interceptors<RequestInit>;
+        response: Interceptors<Response>;
+    };
+}
+export interface ClientOptions {
+    timeout?: number;
+    [key: string]: unknown;
+}
+export type ClientRequest = <E extends AbstractEndpoint>(endpoint: E, options: OptionsWithoutBody<E> | OptionsWithBody<E>) => Promise<ResponseWrapper<EndpointResponseBody<E>>>;
+export type EndpointParameters<E extends AbstractEndpoint> = E['definition']['parameters'];
+export type EndpointPath<E extends AbstractEndpoint> = E['definition']['path'];
+export type EndpointResponse<E extends AbstractEndpoint> = E['definition']['response'];
+export type PaginatedEndpointResponse<E extends AbstractEndpoint> = E['definition']['response'] & {
+    page?: number;
+    size?: number;
+    results?: number;
+};
+export type EndpointBody<E extends AbstractEndpoint> = E['definition']['body'];
+export type EndpointResponseProperty<E extends AbstractEndpoint> = E['responseProperty'] extends string ? E['responseProperty'] : E['property'] extends string ? E['property'] : never;
+type EndpointResponseBodyWrapper<E extends AbstractEndpoint> = EndpointResponseProperty<E>;
+type Page = 'page' | 'size' | 'results';
+export type EndpointResponseBody<E extends AbstractEndpoint> = {
+    [key in EndpointResponseBodyWrapper<E>]: EndpointResponse<E>;
+} & {
+    [key in Page]?: number;
+};
+export interface OptionsWithBody<E extends AbstractEndpoint> {
+    body?: EndpointBody<E>;
+    headers?: RequestHeaders;
+    parameters?: EndpointParameters<E>;
+    path?: EndpointPath<E>;
+    timeout?: number;
+}
+export type OptionsWithoutBody<E extends AbstractEndpoint> = Omit<OptionsWithBody<E>, 'body'>;
+export type Options<E extends AbstractEndpoint> = OptionsWithBody<E> | OptionsWithoutBody<E>;
+export {};

package/lib/model/client/FetchClient.d.ts

@@ -0,0 +1,7 @@
+import { ClientConfig, ClientRequest } from './AbstractClient.types';
+import { AbstractClient } from './AbstractClient';
+
+export declare class FetchClient extends AbstractClient {
+    constructor(config?: ClientConfig);
+    protected request: ClientRequest;
+}

package/lib/model/client/helper/addParameters.d.ts

@@ -0,0 +1,4 @@
+import { AbstractEndpoint } from '../../endpoint/AbstractEndpoint';
+import { EndpointParameters } from '../AbstractClient.types';
+
+export declare const addParameters: <E extends AbstractEndpoint>(path: string, parameters?: EndpointParameters<E>) => string;

package/lib/model/client/helper/addParameters.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/model/client/helper/index.d.ts

@@ -0,0 +1,2 @@
+export * from './addParameters';
+export * from './isJson';

package/lib/model/client/helper/isJson.d.ts

@@ -0,0 +1 @@
+export declare const isJson: (data: string) => boolean;

package/lib/model/client/helper/isJson.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/model/client/index.d.ts

@@ -0,0 +1,4 @@
+export * from './AbstractClient';
+export * from './AbstractClient.types';
+export * from './FetchClient';
+export * from './helper';

package/lib/model/client/middleware/Interceptors.d.ts

@@ -0,0 +1,8 @@
+import { Middleware } from './middleware.types';
+
+export declare class Interceptors<T> {
+    fns: Middleware<T>[];
+    constructor();
+    delete(fn: Middleware<T>): void;
+    use(fn: Middleware<T>): void;
+}

package/lib/model/client/middleware/Interceptors.unit.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/model/client/middleware/middleware.types.d.ts

@@ -0,0 +1 @@
+export type Middleware<T> = (value: T) => T | Promise<T>;

package/lib/model/endpoint/AbstractEndpoint.d.ts

@@ -0,0 +1,57 @@
+import { HttpMethod } from '../../types/request.types';
+import { EndpointDefinition } from './AbstractEndpoint.types';
+
+interface EndpointOptions {
+    headers?: AbstractEndpoint['definition']['headers'];
+    parameters?: AbstractEndpoint['definition']['parameters'];
+}
+export declare abstract class AbstractEndpoint<D = EndpointDefinition> {
+    /**
+     * HTTP method.
+     */
+    readonly method: HttpMethod;
+    /**
+     * Name of the endpoint.
+     */
+    abstract readonly name: string;
+    /**
+     * URL path of the API endpoint. Can contain path variables like `:variable`.
+     */
+    abstract readonly path: string;
+    /**
+     * The property in the request body and response body. If the response body
+     * property differs, set responseProperty alongside property.
+     * If the property is undefined, the endpoint will be called without a namespace.
+     */
+    readonly property: string | undefined;
+    /**
+     * Property used in the response. Falls back to `this.property` if it's not
+     * set.
+     */
+    readonly responseProperty: string | undefined;
+    /**
+     * Timeout in milliseconds.
+     * This is used to override the default timeout of the client.
+     */
+    readonly timeout: number | undefined;
+    /**
+     * Used to expose EndpointDefinition type.
+     */
+    readonly definition: D;
+    /**
+     * Headers to include when calling this endpoint.
+     */
+    private readonly headers;
+    /**
+     * Parameters to include in the endpoint url.
+     */
+    private readonly parameters;
+    constructor(options?: EndpointOptions);
+    getHeaders(): AbstractEndpoint['definition']['headers'];
+    getParameters(): AbstractEndpoint['definition']['parameters'];
+    getPath(): AbstractEndpoint['path'];
+    getProperty(): AbstractEndpoint['property'];
+    getResponseProperty(): AbstractEndpoint['responseProperty'];
+    getTimeout(): AbstractEndpoint['timeout'];
+}
+export {};

package/lib/model/endpoint/AbstractEndpoint.types.d.ts

@@ -0,0 +1,21 @@
+import { OneOrMore } from '@myparcel-dev/ts-utils';
+import { RequestHeaders } from '../../types/request.types';
+import { NoInfer } from '../../types/global.types';
+
+type Pagination = {
+    page?: number;
+    size?: number;
+    results?: number;
+};
+export type PaginatedResponse<T> = Pagination & Record<string, T>;
+export interface EndpointDefinition {
+    name: string;
+    body?: NoInfer<unknown>;
+    headers?: RequestHeaders;
+    parameters?: NoInfer<Record<string, string | number | boolean>>;
+    path?: Record<string, string | number>;
+    response?: NoInfer<OneOrMore<unknown>> | PaginatedResponse<NoInfer<unknown[]>>;
+    timeout?: number;
+}
+export type CreateDefinition<D extends EndpointDefinition> = D;
+export {};

package/lib/model/endpoint/AbstractPrivateEndpoint.d.ts

@@ -0,0 +1,14 @@
+import { RequestHeaders } from '../../types/request.types';
+import { EndpointDefinition } from './AbstractEndpoint.types';
+import { AbstractEndpoint } from './AbstractEndpoint';
+
+type PrivateEndpointDefinition = {
+    headers: RequestHeaders & {
+        Authorization: string;
+    };
+};
+type Private<D = EndpointDefinition> = D & PrivateEndpointDefinition;
+export declare abstract class AbstractPrivateEndpoint<D = EndpointDefinition> extends AbstractEndpoint<Private<D>> {
+    abstract readonly name: AbstractPrivateEndpoint['definition']['name'];
+}
+export {};

package/lib/model/endpoint/AbstractPublicEndpoint.d.ts

@@ -0,0 +1,6 @@
+import { EndpointDefinition } from './AbstractEndpoint.types';
+import { AbstractEndpoint } from './AbstractEndpoint';
+
+export declare abstract class AbstractPublicEndpoint<D = EndpointDefinition> extends AbstractEndpoint<D> {
+    abstract readonly name: AbstractPublicEndpoint['definition']['name'];
+}

package/lib/model/endpoint/index.d.ts

@@ -0,0 +1,4 @@
+export * from './AbstractEndpoint';
+export * from './AbstractEndpoint.types';
+export * from './AbstractPrivateEndpoint';
+export * from './AbstractPublicEndpoint';

package/lib/model/exception/ApiException.d.ts

@@ -0,0 +1,6 @@
+import { ErrorResponse } from '../../types/request.types';
+
+export declare class ApiException extends Error {
+    data: ErrorResponse;
+    constructor(error: ErrorResponse);
+}

package/lib/model/exception/UserException.d.ts

@@ -0,0 +1,4 @@
+export declare class UserException extends Error {
+    name: string;
+    constructor(message: string);
+}

package/lib/model/exception/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ApiException';
+export * from './UserException';

package/lib/model/index.d.ts

@@ -0,0 +1,3 @@
+export * from './client';
+export * from './endpoint';
+export * from './exception';

package/lib/types/common.types.d.ts

@@ -0,0 +1,31 @@
+export interface Address {
+    area?: string;
+    box_number?: string;
+    cc: string;
+    city: string;
+    company?: string;
+    eori_number?: string;
+    number?: string;
+    number_suffix?: string;
+    person: string;
+    postal_code: string;
+    region?: string;
+    state?: string;
+    street: string;
+    street_additional_info?: string;
+    vat_number?: string;
+}
+export interface AddressWithContactDetails extends Address {
+    email?: string;
+    phone?: string;
+}
+export interface RetailLocation {
+    cc: string;
+    city: string;
+    location_code: string;
+    location_name: string;
+    number: string;
+    postal_code: string;
+    retail_network_id: string;
+    street: string;
+}

package/lib/types/data.types.d.ts

@@ -0,0 +1,23 @@
+export type Weekday = 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday';
+export type IntBoolean = 0 | 1;
+export interface Price {
+    amount: number;
+    currency: 'EUR' | string;
+}
+export interface StartEndDate {
+    end: Timestamp;
+    start: Timestamp;
+}
+export interface EnumSchema<Type> {
+    enum: Type[];
+    type: Type extends boolean ? 'boolean' : string;
+}
+export interface Timestamp {
+    date: string;
+    timezone: string;
+    timezone_type: number;
+}
+export type PaginationParameters = {
+    page: number;
+    size: number;
+};

package/lib/types/global.types.d.ts

@@ -0,0 +1,4 @@
+export type NoInfer<T> = [T][T extends never ? 0 : never];
+export type WithRequired<T, K extends keyof T> = T & {
+    [P in K]-?: T[P];
+};

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './common.types';
+export * from './data.types';
+export * from './global.types';
+export * from './request.types';

package/lib/types/request.types.d.ts

@@ -0,0 +1,18 @@
+export type HttpMethodWithBody = 'POST' | 'PATCH' | 'PUT';
+export type HttpMethodWithoutBody = 'GET' | 'OPTIONS' | 'DELETE' | 'HEAD';
+export type HttpMethod = HttpMethodWithBody | HttpMethodWithoutBody;
+export type RequestHeader = 'Content-Type' | 'Authorization' | 'Accept' | 'Accept-Language';
+export type RequestHeaders = Record<RequestHeader | string, string>;
+export interface ResponseWrapper<Data = Record<string, unknown>> {
+    data: Data;
+}
+export interface ErrorResponse {
+    message: string;
+    request_id: string;
+    errors: {
+        status?: number;
+        code: number;
+        title?: string;
+        message: string;
+    }[];
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@myparcel-dev/sdk",
+  "version": "5.0.0",
+  "description": "JavaScript SDK to connect to the MyParcel API via Node.js or browser",
+  "keywords": [
+    "myparcel",
+    "sdk",
+    "node",
+    "browser"
+  ],
+  "repository": "github:myparcelnl/js-sdk",
+  "license": "MIT",
+  "author": "Edie Lemoine <edie@myparcel.nl>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.cjs"
+    }
+  },
+  "main": "./lib/index.cjs",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "build:dev": "vite build --mode development",
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:run": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "watch": "yarn build:dev --watch"
+  },
+  "lint-staged": {
+    "*.{ts,js,cjs.mjs}": "eslint --fix",
+    "*.{json,yml,md}": "prettier --write",
+    "package.json": [
+      "sort-package-json",
+      "sh -c \"publint\""
+    ]
+  },
+  "prettier": "@myparcel-dev/prettier-config",
+  "dependencies": {
+    "@myparcel-dev/constants": "^2.7.0",
+    "@myparcel-dev/ts-utils": "^1.15.0"
+  },
+  "devDependencies": {
+    "@myparcel-dev/eslint-config-esnext": "^1.4.0",
+    "@myparcel-dev/eslint-config-import": "^1.3.0",
+    "@myparcel-dev/eslint-config-node": "^1.4.0",
+    "@myparcel-dev/eslint-config-prettier": "^1.4.0",
+    "@myparcel-dev/eslint-config-prettier-typescript": "^1.4.0",
+    "@myparcel-dev/semantic-release-config": "^6.0.0",
+    "@tsconfig/recommended": "^1.0.2",
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "@vitest/ui": "^2.0.0",
+    "eslint": "^8.34.0",
+    "eslint-plugin-sort-exports": "^0.9.0",
+    "husky": "^9.0.0",
+    "prettier": "^2.8.4",
+    "publint": "^0.2.0",
+    "sort-package-json": "^2.4.1",
+    "typescript": "^5.2.0",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.6.0",
+    "vitest": "^2.0.0"
+  },
+  "volta": {
+    "node": "20.10.0",
+    "yarn": "4.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}