@deliverart/sdk-js-global-types

Shared types and utilities package for the DeliverArt JavaScript SDK.

Installation

npm install @deliverart/sdk-js-global-types

Exported Types

Common Schemas

Address

interface Address {
  street: string
  city: string
  postalCode: string
  country: string
  state?: string
  province?: string
  line1?: string
  line2?: string
}

Location

interface Location {
  latitude: number
  longitude: number
}

BillingData

interface BillingData {
  email: string
  pec?: string
  sdi?: string
  phone?: string
}

Pagination

interface Pagination {
  currentPage: number
  itemsPerPage: number
  totalItems: number
  totalPages: number
}

Paginated

interface Paginated<T> {
  data: T[]
  pagination: Pagination
}

Utility Types

SortDir

type SortDir = 'asc' | 'desc'

DatetimeFilter

interface DatetimeFilter {
  before?: string
  after?: string
  strictly_before?: string
  strictly_after?: string
}

IRI Helpers

iriSchema

Creates a schema for API resource IRIs.

import { iriSchema } from '@deliverart/sdk-js-global-types';

const userIriSchema = iriSchema('/users/:id');
// Validates strings like: /users/123

iriNullableSchema

Creates a schema for nullable API resource IRIs.

import { iriNullableSchema } from '@deliverart/sdk-js-global-types';

const userNullableIriSchema = iriNullableSchema('/users/:id');
// Validates strings like: /users/123 or null

Utility Functions

createPaginatedSchema

Creates a Zod schema for paginated responses.

import { createPaginatedSchema } from '@deliverart/sdk-js-global-types';
import { z } from 'zod';

const userSchema = z.object({
  id: z.string(),
  name: z.string()
});

const paginatedUsersSchema = createPaginatedSchema(userSchema);
// Type: Paginated<User>

responseToPagination

Extracts pagination info from API response headers.

import { responseToPagination } from '@deliverart/sdk-js-global-types';

parseResponse(data: unknown, rawResponse: Response): Paginated<User> {
  const users = z.array(userSchema).parse(data);
  
  return {
    data: users,
    pagination: responseToPagination(rawResponse)
  };
}

Usage Examples

Using Address Schema

import { addressSchema } from '@deliverart/sdk-js-global-types';
import { z } from 'zod';

const createOrderSchema = z.object({
  customerAddress: addressSchema.required(),
  billingAddress: addressSchema.optional()
});

Using Pagination

import { Paginated } from '@deliverart/sdk-js-global-types';

function displayUsers(result: Paginated<User>) {
  console.log(`Page ${result.pagination.currentPage} of ${result.pagination.totalPages}`);
  console.log(`Total items: ${result.pagination.totalItems}`);
  
  result.data.forEach(user => {
    console.log(user.name);
  });
}

Using IRI Validators

import { iriSchema } from '@deliverart/sdk-js-global-types';

const productIriSchema = iriSchema('/products/:id');

// Valid
productIriSchema.parse('/products/123'); // ✓

// Invalid
productIriSchema.parse('/users/123'); // ✗ Throws validation error
productIriSchema.parse('invalid'); // ✗ Throws validation error

Constants

Countries

export const COUNTRIES = ['IT', 'US', 'UK', /* ... */] as const;

Locales

export const LOCALES = ['it_IT', 'en_US', 'en_GB', /* ... */] as const;

License

MIT