smklog 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitrii T
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# smklog
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official JavaScript / TypeScript client for the [SMKlog Quote API](https://smklog.com/developers/):
+live USPS, UPS, FedEx and DHL Express parcel rates from a US origin, a checkout handed to a
+human, and where that checkout stands. No API key, no account.
+
+ESM, Node 18 or newer (global `fetch`), no dependencies, no build step: one `index.js` and
+its `index.d.ts`.
+
+## Install
+
+```
+npm install smklog
+```
+
+## Quickstart
+
+```js
+import { SmklogClient } from 'smklog';
+
+const client = new SmklogClient();
+const product = 'Yamaha FG800 acoustic guitar in a hard case';
+const quote = await client.getParcelQuote({ product, from_postal_code: '07102', to_postal_code: '30303' });
+const best = quote.isPriced() ? quote.cheapest() : null;
+if (!best) throw new Error(`${quote.mode}: ${quote.notice}`);        // not_a_parcel, review, ...
+console.log(best.carrier, best.service, best.amount);                 // USPS Ground Advantage 38.42
+// quote_id is good for 15 minutes; a session opened with it reuses these rates, so the pair
+// costs one carrier call. It is null when the handle was not stored: then price live.
+const session = await client.createPaymentSession(quote.quote_id
+  ? { quote_id: quote.quote_id, service: best.service }
+  : { product, from_zip: '07102', to_zip: '30303', service: best.service });
+console.log(session.handoff_url, session.quote_reused);               // the human pays here; true
+if (session.session_id) {
+  const status = await client.getCheckoutStatus(session.session_id);
+  console.log(status.status);                                         // awaiting_checkout ... label_ready
+}
+```
+
+The same snippet compiles as TypeScript under `--strict`: `cheapest()` is `Rate | null`,
+`quote_id` is `string | null | undefined` and `session_id` is `string | null`, so all three are
+checked before use.
+
+Every `getParcelQuote` call spends a live carrier rating that costs SMKlog money: one call per
+shipment, cache on your side, never poll. Pass the answer's `quote_id` to `createPaymentSession`
+and the pair costs one carrier call; a session opened from the shipment fields alone prices the
+shipment again. Quote once, let the human settle on the parcel, then open one session.
+
+## Operations
+
+| Method | Endpoint | Returns |
+| --- | --- | --- |
+| `getParcelQuote(request)` | `POST /quote` | `QuoteResponse` |
+| `createPaymentSession(request)` | `POST /agent/checkout-session` | `CheckoutSession` |
+| `getCheckoutStatus(sessionId)` | `GET /agent/checkout-session/{session_id}` | `CheckoutStatus` |
+| `status()` | `GET /status` | `Liveness` |
+
+Field names are `snake_case` exactly as the API sends and receives them; the client renames
+nothing and keeps fields it does not know about.
+
+`getParcelQuote` resolves to a `QuoteResponse` object: the wire fields are its own properties
+(so `JSON.stringify(quote)` is the raw answer) and two helpers live on its prototype:
+
+- `quote.cheapest()`: the rate with the lowest `amount`, or `null` when there are none.
+- `quote.isPriced()`: `true` when `mode` is `parcel_label_ready` and at least one rate came back.
+
+`quote.rates` stays in the API's order (best value first).
+
+`createPaymentSession` takes one of two forms:
+
+- `{ quote_id, service? }` (preferred): `quote_id` is the handle a `getParcelQuote` answer carries,
+  valid 15 minutes. The session reuses that quote's rates, no second carrier call is spent, and
+  the answer says so with `quote_reused: true`. The shipment fields are ignored while the handle
+  is valid.
+- `{ product, from_zip, to_zip, to_country?, quantity?, service? }`: the shipment itself, priced
+  live when the checkout opens. `quantity` is sent as `1` when omitted.
+
+An expired `quote_id` makes the API price the shipment fields live instead, so pass them
+alongside an old id when you have them. `quote.quote_id` is `null` when nothing was priced or the
+handle could not be stored, and absent on answers without rates; the client passes a `quote_id`
+through as given and never invents one.
+
+## Options
+
+```js
+new SmklogClient({
+  baseUrl: 'https://quote-api.smklog.com', // default
+  timeout: 30_000,                         // ms per attempt; a quote can take 10-20 s
+  token: undefined,                        // OAuth bearer for a dedicated rate-limit bucket
+  userAgent: 'my-app/2.0',                 // appended after smklog-sdk-javascript/0.1.0
+});
+```
+
+## Errors
+
+Every failure is a `SmklogError` with `status` (HTTP status, `0` when no response arrived),
+`error` (the API's stable code), `message`, `missing` (field names, may be empty) and `body`
+(the parsed `Problem`, or the raw text when the body was not JSON). When the `Problem` carries
+no `message`, the SDK's message is the code plus the missing fields
+(`missing_required_fields: missing to_postal_code`). Subclasses by code:
+
+| `error` code | Class |
+| --- | --- |
+| `rate_limited`, `slow_down`, and any other 429 (an edge rate limit without a `Problem` body reads `rate_limited`) | `RateLimitedError` (`retryAfter` seconds when the API sent the header) |
+| `product_not_recognized`, `product_url_not_detected`, `missing_required_fields`, `invalid_request`, `invalid_json` | `InvalidRequestError` |
+| `session_not_found` | `NotFoundError` |
+| `session_failed` | `SessionFailedError` |
+| anything else | `SmklogError` |
+
+Network failures and timeouts raise `SmklogError` with `status: 0`, `error: 'network_error'`
+and the native error as `cause`.
+
+Local validation runs before any request and raises `InvalidRequestError` with `status: 0`:
+a 5-digit US origin ZIP (and destination ZIP on US lanes), `to_country_code` in `US, CA, GB,
+DE, AU`, `quantity` an integer of 1 or more, and the four measurements (`length_cm`,
+`width_cm`, `height_cm`, `weight_kg`) all or none. `quantity` is sent as `1` when omitted.
+
+```js
+import { SmklogError, RateLimitedError } from 'smklog';
+
+try {
+  await client.getParcelQuote(request);
+} catch (error) {
+  if (error instanceof RateLimitedError) scheduleForLater(error.retryAfter);
+  else if (error instanceof SmklogError) console.error(error.status, error.error, error.message);
+  else throw error;
+}
+```
+
+### Retries and rate limits
+
+- **A 429 is never retried.** The buckets are hourly (about 80 quotes, 60 status reads, 20
+  token requests per client); a retry loop only burns the bucket faster. The caller decides.
+- `getCheckoutStatus` and `status` are retried at most twice, with a short backoff, on
+  network failures and 5xx answers.
+- `getParcelQuote` and `createPaymentSession` are never retried automatically: a quote spends
+  a live carrier rating, a session opens a checkout.
+- Each attempt is bounded by `timeout` through an `AbortController`.
+
+## TypeScript
+
+`index.d.ts` declares the client, its options, every model from the published JSON Schemas
+(`QuoteRequest`, `QuoteResponse`, `Rate`, `Package`, `CheckoutSessionRequest`,
+`CheckoutSession`, `CheckoutStatus`, `Liveness`, `Problem`) and the error classes, `cause`
+included, so the declarations hold on any `target` and `lib`.
+
+## Tests
+
+```
+node --test
+```
+
+The tests replay the example payloads vendored in `../testdata/` from a local HTTP server and
+never reach the network. `SMKLOG_LIVE=1 node --test` adds one live call to `status()`
+against production; nothing in the suite ever calls `POST /quote` for real.
+
+## Links
+
+- Developer portal: https://smklog.com/developers/
+- OpenAPI 3.1 contract: https://quote-api.smklog.com/openapi.json
+- Rate limits: https://smklog.com/developers/rate-limits
+- Status: https://smklog.com/developers/status
+
+MIT license; see [LICENSE](LICENSE).

package/index.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Type declarations for the SMKlog Quote API client (package "smklog").
+ *
+ * Models mirror testdata/schemas/*.schema.json field for field; property
+ * names are snake_case exactly as they travel on the wire.
+ */
+
+/** SDK version, also the version in the User-Agent header. */
+export const VERSION: string;
+
+export interface SmklogClientOptions {
+  /** API origin. Default "https://quote-api.smklog.com". */
+  baseUrl?: string;
+  /** Per-attempt timeout in milliseconds. Default 30000: a quote can take 10-20 s while carriers answer. */
+  timeout?: number;
+  /** Optional OAuth bearer for a dedicated rate-limit bucket; sent as "Authorization: Bearer ..." only when set. */
+  token?: string;
+  /** Appended after the SDK's own product token: "smklog-sdk-javascript/0.1.0 <userAgent>". */
+  userAgent?: string;
+}
+
+export type CountryCode = 'US' | 'CA' | 'GB' | 'DE' | 'AU';
+export type Carrier = 'USPS' | 'UPS' | 'FedEx' | 'DHL';
+export type PackageConfidence = 'low' | 'medium' | 'high' | 'manual';
+export type QuoteMode =
+  | 'parcel_label_ready'
+  | 'not_a_parcel'
+  | 'multiple_boxes'
+  | 'international_unsupported_online'
+  | 'parcel_restricted'
+  | 'review'
+  | 'parcel_rates_unavailable';
+export type CheckoutStage =
+  | 'awaiting_checkout'
+  | 'checkout_started'
+  | 'paid'
+  | 'label_ready'
+  | 'delivered'
+  | 'refunded';
+
+/** One shipment to price (schema QuoteRequest). */
+export interface QuoteRequest {
+  /** Plain-words item description. Required unless product_url is given. */
+  product?: string;
+  /** Store product page URL; the item is identified from the page. Alternative to product. */
+  product_url?: string;
+  /** How many of the item ship together. The SDK sends 1 when omitted. */
+  quantity?: number;
+  /** 5-digit US ZIP; the origin is always in the United States. */
+  from_postal_code: string;
+  /** 5-digit US ZIP for US lanes, otherwise the destination country's own postal code. */
+  to_postal_code: string;
+  /** Destination country, default US. */
+  to_country_code?: CountryCode;
+  /** Packed box length, cm. Send all four measurements or none. */
+  length_cm?: number;
+  /** Packed box width, cm. */
+  width_cm?: number;
+  /** Packed box height, cm. */
+  height_cm?: number;
+  /** Packed weight, kg. */
+  weight_kg?: number;
+  /** Set to "manual" when supplying exact dimensions. */
+  package_source?: 'manual';
+}
+
+/** The packed box used for pricing (schema Package). */
+export interface Package {
+  quantity?: number;
+  length_cm?: number;
+  width_cm?: number;
+  height_cm?: number;
+  weight_kg?: number;
+  description?: string;
+  /** "manual" when the caller supplied the measurements. */
+  confidence?: PackageConfidence;
+  assumptions?: string[];
+}
+
+/** One purchasable service (schema Rate). */
+export interface Rate {
+  carrier: Carrier;
+  /** Service display name, e.g. "Ground Advantage". */
+  service: string;
+  /** Carrier service code, stable across calls. */
+  service_code?: string;
+  /** Checkout total, USD, SMKlog fee inside. */
+  amount: number;
+  /** Carrier retail counter price, USD; 0 when not published. */
+  retail_amount?: number;
+  delivery_days?: number | null;
+  /** e.g. "2-5 business days". */
+  delivery_window?: string | null;
+  /** ISO date the carrier estimates. */
+  delivery_estimated_date?: string | null;
+  currency: 'USD';
+}
+
+/** The wire fields of a quote answer (schema QuoteResponse, additionalProperties true). */
+export interface QuoteResponseData {
+  /** Only parcel_label_ready carries rates. */
+  mode: QuoteMode;
+  identified_product_title?: string;
+  /** Handle for createPaymentSession, valid 15 minutes; null when nothing was priced or the handle could not be stored, absent on answers without rates. */
+  quote_id?: string | null;
+  package?: Package;
+  /** Every box the estimate produced; one entry when the shipment is one parcel. */
+  packages?: Package[];
+  /** Up to five purchasable services, best value first. */
+  rates: Rate[];
+  dangerous_goods?: Record<string, unknown> | null;
+  /** Product pages the estimate read, when a search informed it. */
+  sources?: Array<{ title?: string; url?: string }>;
+  /** Human-readable reason when mode is not parcel_label_ready. */
+  notice?: string | null;
+  source?: { package?: string; rates?: string; [key: string]: unknown };
+  [key: string]: unknown;
+}
+
+/**
+ * What getParcelQuote resolves to: the wire fields as own properties (so
+ * JSON.stringify gives the raw answer) plus two helpers on the prototype.
+ */
+export interface QuoteResponse extends QuoteResponseData {}
+export class QuoteResponse {
+  constructor(body: QuoteResponseData);
+  /** The rate with the lowest amount, or null when there are no rates. */
+  cheapest(): Rate | null;
+  /** True when mode is parcel_label_ready and at least one rate came back. */
+  isPriced(): boolean;
+}
+
+/** The shipment to open a checkout for (schema CheckoutSessionRequest). */
+export interface CheckoutSessionRequest {
+  /** The quote_id a getParcelQuote answer carries, valid 15 minutes: the session reuses that quote's rates and the shipment fields are ignored. An expired handle makes the API price the shipment fields live, so send them alongside an old id when you have them. */
+  quote_id?: string;
+  /** Required unless quote_id is given. */
+  product?: string;
+  /** 5-digit US ZIP. Required unless quote_id is given. */
+  from_zip?: string;
+  /** 5-digit US ZIP, or the destination country's own postal code. Required unless quote_id is given. */
+  to_zip?: string;
+  to_country?: CountryCode;
+  /** The SDK sends 1 when omitted and no quote_id is given. */
+  quantity?: number;
+  /** Service to anchor the amount to, matched as a case-insensitive fragment; cheapest when omitted. */
+  service?: string;
+}
+
+/** A payment session, not a charge (schema CheckoutSession). */
+export interface CheckoutSession {
+  intent: 'session';
+  /** Handle for getCheckoutStatus, good for 30 days; null only when the session record could not be stored. */
+  session_id?: string | null;
+  method?: string[];
+  /** Live-quoted checkout total for the anchored service, USD. */
+  amount: number;
+  currency: 'USD';
+  service?: string;
+  /** Opens the SMKlog checkout prefilled with this shipment. */
+  handoff_url: string;
+  identified_product_title?: string;
+  /** True when the amount came from a quote_id, so no carrier call was spent. */
+  quote_reused?: boolean;
+  note?: string;
+}
+
+/** The checkout a human started, nested in CheckoutStatus. */
+export interface CheckoutStatusCheckout {
+  /** SMKlog order id, the reference for support. */
+  order_id?: string;
+  started_at?: string;
+  paid?: boolean;
+  label_ready?: boolean;
+  refunded?: boolean;
+  carrier?: string | null;
+  /** The service the human actually chose. */
+  service?: string | null;
+  /** Present from label_ready on. */
+  tracking_number?: string | null;
+  tracking_status?: string | null;
+  /** ISO date when the carrier gives one. */
+  estimated_delivery?: string | null;
+  delivered_at?: string | null;
+}
+
+/** Where a checkout stands (schema CheckoutStatus). Never carries names, addresses or emails. */
+export interface CheckoutStatus {
+  session_id: string;
+  status: CheckoutStage;
+  created_at?: string;
+  expires_at?: string;
+  amount?: number;
+  currency?: 'USD';
+  service?: string;
+  quote_reused?: boolean;
+  /** Null while awaiting_checkout. */
+  checkout?: CheckoutStatusCheckout | null;
+  /** What, if anything, the agent should do now. */
+  next?: string;
+}
+
+/** The liveness answer (schema Liveness). */
+export interface Liveness {
+  ok: true;
+  service: 'smklog-quote-api';
+  /** Product version shared by the OpenAPI, the MCP server and the agent card. */
+  version: string;
+  /** Server time, ISO 8601. */
+  time: string;
+  last_estimate_race?: Record<string, unknown> | null;
+}
+
+/** Every error answer on the host (schema Problem). */
+export interface Problem {
+  /** Stable code, e.g. rate_limited, missing_required_fields, session_not_found. */
+  error: string;
+  message?: string;
+  /** Field names still needed. */
+  missing?: string[];
+}
+
+export interface SmklogErrorOptions {
+  status?: number;
+  error?: string;
+  missing?: string[];
+  body?: unknown;
+  cause?: unknown;
+}
+
+/** Base error: every failure the client raises, local or from the API. */
+export class SmklogError extends Error {
+  /** HTTP status; 0 when no response arrived (network failure, timeout) or the request was rejected locally. */
+  readonly status: number;
+  /** Stable code: the API's own (rate_limited, session_not_found, ...), network_error, http_error, invalid_response, or invalid_request / missing_required_fields for local validation. A 429 without a Problem body reads rate_limited. */
+  readonly error: string;
+  /** Field names still needed; empty unless the code says otherwise. */
+  readonly missing: string[];
+  /** The parsed Problem, the raw body text when it was not JSON, or null. */
+  readonly body: unknown;
+  /** The native error behind a network_error, else undefined. Declared here so it exists whatever lib the consumer targets. */
+  readonly cause?: unknown;
+  constructor(message: string, options?: SmklogErrorOptions);
+}
+
+/** Every 429: rate_limited, slow_down, or an edge rate limit without a Problem body. The SDK never retries it; the caller decides. */
+export class RateLimitedError extends SmklogError {
+  /** Seconds from the Retry-After header when the API sent one, else null. */
+  readonly retryAfter: number | null;
+  constructor(message: string, options?: SmklogErrorOptions & { retryAfter?: number | null });
+}
+
+/** product_not_recognized, product_url_not_detected, missing_required_fields, invalid_request, invalid_json, and local validation failures (status 0). */
+export class InvalidRequestError extends SmklogError {}
+
+/** session_not_found. */
+export class NotFoundError extends SmklogError {}
+
+/** session_failed: the API could not open a checkout for this shipment. */
+export class SessionFailedError extends SmklogError {}
+
+export class SmklogClient {
+  readonly baseUrl: string;
+  readonly timeout: number;
+  readonly token: string | null;
+  /** The full User-Agent sent, SDK product token first. */
+  readonly userAgent: string;
+  constructor(options?: SmklogClientOptions);
+  /** POST /quote. Spends a live carrier rating; never retried. */
+  getParcelQuote(request: QuoteRequest): Promise<QuoteResponse>;
+  /** POST /agent/checkout-session. Opens a checkout for a human; nothing is charged. Never retried. */
+  createPaymentSession(request: CheckoutSessionRequest): Promise<CheckoutSession>;
+  /** GET /agent/checkout-session/{session_id}. Retried up to twice on network failure or 5xx. */
+  getCheckoutStatus(sessionId: string): Promise<CheckoutStatus>;
+  /** GET /status. Retried up to twice on network failure or 5xx. */
+  status(): Promise<Liveness>;
+}

package/index.js

@@ -0,0 +1,283 @@
+// SMKlog Quote API client. Thin by design: four operations, validation that
+// saves a wasted request, and errors typed by the API's own error codes.
+// Wire field names stay snake_case exactly as the API sends them.
+
+export const VERSION = '0.1.0';
+
+const DEFAULT_BASE_URL = 'https://quote-api.smklog.com';
+// Carriers answer in 10-20 s on a cold lane, so the default is generous.
+const DEFAULT_TIMEOUT_MS = 30_000;
+// Retry only the idempotent GETs, and only a little: a status read that
+// fails three times in a row is an outage the caller should see.
+const MAX_GET_ATTEMPTS = 3;
+const BACKOFF_MS = 200;
+
+const COUNTRIES = new Set(['US', 'CA', 'GB', 'DE', 'AU']);
+const US_ZIP = /^[0-9]{5}$/;
+const MEASUREMENTS = ['length_cm', 'width_cm', 'height_cm', 'weight_kg'];
+
+// --- Errors ---------------------------------------------------------------
+
+export class SmklogError extends Error {
+  constructor(message, { status = 0, error = 'network_error', missing = [], body = null, cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = this.constructor.name;
+    this.status = status;
+    this.error = error;
+    this.missing = Array.isArray(missing) ? missing : [];
+    this.body = body;
+  }
+}
+
+export class RateLimitedError extends SmklogError {
+  constructor(message, options = {}) {
+    super(message, options);
+    // The API does not promise a Retry-After header; expose it when present so
+    // the caller (never the SDK) can decide when to come back.
+    this.retryAfter = options.retryAfter ?? null;
+  }
+}
+
+export class InvalidRequestError extends SmklogError {}
+
+export class NotFoundError extends SmklogError {}
+
+export class SessionFailedError extends SmklogError {}
+
+const ERROR_CLASS_BY_CODE = {
+  rate_limited: RateLimitedError,
+  slow_down: RateLimitedError,
+  product_not_recognized: InvalidRequestError,
+  product_url_not_detected: InvalidRequestError,
+  missing_required_fields: InvalidRequestError,
+  invalid_request: InvalidRequestError,
+  invalid_json: InvalidRequestError,
+  session_not_found: NotFoundError,
+  session_failed: SessionFailedError,
+};
+
+function errorFromResponse(response, problem, rawText) {
+  const isProblem = problem && typeof problem === 'object' && typeof problem.error === 'string';
+  // An edge rate limit answers 429 with an HTML or empty body instead of the
+  // worker's Problem; it still must not be retried, so the status alone
+  // decides the class and the code when the body names none.
+  const rateLimited = response.status === 429;
+  const error = isProblem ? problem.error : rateLimited ? 'rate_limited' : 'http_error';
+  const missing = isProblem && Array.isArray(problem.missing) ? problem.missing : [];
+  // A Problem may carry no sentence (missing_required_fields lists fields
+  // instead), and a log line of error.message should still say what went wrong.
+  const message = (isProblem && problem.message)
+    || (isProblem ? `${error}${missing.length ? ': missing ' + missing.join(', ') : ''}` : `HTTP ${response.status} from ${response.url}`);
+  const ErrorClass = rateLimited ? RateLimitedError : ERROR_CLASS_BY_CODE[error] || SmklogError;
+  const retryAfterHeader = Number(response.headers.get('retry-after'));
+  return new ErrorClass(message, {
+    status: response.status,
+    error,
+    missing,
+    body: isProblem ? problem : rawText,
+    retryAfter: Number.isFinite(retryAfterHeader) && retryAfterHeader > 0 ? retryAfterHeader : null,
+  });
+}
+
+// Local validation failures reuse the API's own codes so one catch handles
+// both; status 0 tells them apart from a refusal the server actually sent.
+function invalid(message, missing = []) {
+  return new InvalidRequestError(message, {
+    status: 0,
+    error: missing.length ? 'missing_required_fields' : 'invalid_request',
+    missing,
+  });
+}
+
+// --- Models ---------------------------------------------------------------
+
+// The quote body plus two conveniences. Own properties are exactly the wire
+// fields (unknown ones included), so JSON.stringify(quote) is the raw answer.
+export class QuoteResponse {
+  constructor(body) {
+    Object.assign(this, body);
+  }
+
+  isPriced() {
+    return this.mode === 'parcel_label_ready' && Array.isArray(this.rates) && this.rates.length > 0;
+  }
+
+  cheapest() {
+    let best = null;
+    for (const rate of Array.isArray(this.rates) ? this.rates : []) {
+      if (typeof rate.amount === 'number' && (best === null || rate.amount < best.amount)) best = rate;
+    }
+    return best;
+  }
+}
+
+// --- Validation -----------------------------------------------------------
+
+function requireObject(request, name) {
+  if (!request || typeof request !== 'object' || Array.isArray(request)) {
+    throw invalid(`${name} must be an object`);
+  }
+}
+
+// The origin is always a US ZIP; the destination is one only for US lanes.
+function validateRoute(request, fromKey, toKey, countryKey) {
+  const missing = [fromKey, toKey].filter((key) => request[key] === undefined || request[key] === null || request[key] === '');
+  if (missing.length) throw invalid(`${missing.join(', ')} required`, missing);
+
+  const country = request[countryKey];
+  if (country !== undefined && !COUNTRIES.has(country)) {
+    throw invalid(`${countryKey} must be one of ${[...COUNTRIES].join(', ')} (got ${JSON.stringify(country)})`);
+  }
+  if (!US_ZIP.test(String(request[fromKey]))) {
+    throw invalid(`${fromKey} must be a 5-digit US ZIP (got ${JSON.stringify(request[fromKey])})`);
+  }
+  const to = request[toKey];
+  if (country === undefined || country === 'US') {
+    if (!US_ZIP.test(String(to))) throw invalid(`${toKey} must be a 5-digit US ZIP (got ${JSON.stringify(to)})`);
+  } else if (typeof to !== 'string' || to.length > 12) {
+    throw invalid(`${toKey} must be the destination postal code, up to 12 characters (got ${JSON.stringify(to)})`);
+  }
+
+  const quantity = request.quantity;
+  if (quantity !== undefined && (!Number.isInteger(quantity) || quantity < 1)) {
+    throw invalid(`quantity must be an integer of 1 or more (got ${JSON.stringify(quantity)})`);
+  }
+}
+
+function validateQuoteRequest(request) {
+  requireObject(request, 'quote request');
+  if (!request.product && !request.product_url) throw invalid('product or product_url required', ['product']);
+  validateRoute(request, 'from_postal_code', 'to_postal_code', 'to_country_code');
+
+  // An exact box needs all four numbers; a partial set would silently fall
+  // back to the estimate and price a different parcel than the caller meant.
+  const given = MEASUREMENTS.filter((key) => request[key] !== undefined && request[key] !== null);
+  if (given.length !== 0 && given.length !== MEASUREMENTS.length) {
+    throw invalid(`send all of ${MEASUREMENTS.join(', ')} or none of them (got ${given.join(', ')})`);
+  }
+  for (const key of given) {
+    if (typeof request[key] !== 'number' || !Number.isFinite(request[key]) || request[key] <= 0) {
+      throw invalid(`${key} must be a positive number (got ${JSON.stringify(request[key])})`);
+    }
+  }
+}
+
+function validateCheckoutSessionRequest(request) {
+  requireObject(request, 'checkout session request');
+  if (request.quote_id !== undefined && request.quote_id !== null) {
+    if (typeof request.quote_id !== 'string' || request.quote_id === '') throw invalid('quote_id must be a non-empty string');
+    return;
+  }
+  if (!request.product) throw invalid('product required when quote_id is not given', ['product']);
+  validateRoute(request, 'from_zip', 'to_zip', 'to_country');
+}
+
+// --- Client ---------------------------------------------------------------
+
+export class SmklogClient {
+  constructor({ baseUrl = DEFAULT_BASE_URL, timeout = DEFAULT_TIMEOUT_MS, token, userAgent } = {}) {
+    this.baseUrl = String(baseUrl).replace(/\/+$/, '');
+    this.timeout = timeout;
+    this.token = token || null;
+    this.userAgent = userAgent ? `smklog-sdk-javascript/${VERSION} ${userAgent}` : `smklog-sdk-javascript/${VERSION}`;
+  }
+
+  async getParcelQuote(request) {
+    validateQuoteRequest(request);
+    // quantity is required on the wire with a documented default of 1.
+    const body = await this.#request('POST', '/quote', { quantity: 1, ...request });
+    return new QuoteResponse(body);
+  }
+
+  async createPaymentSession(request) {
+    validateCheckoutSessionRequest(request);
+    // A quote_id names the shipment, so no quantity default is added; shipment
+    // fields sent alongside it ride through untouched for the case where the
+    // handle has expired and the API prices them live instead.
+    const body = request.quote_id ? { ...request } : { quantity: 1, ...request };
+    return this.#request('POST', '/agent/checkout-session', body);
+  }
+
+  async getCheckoutStatus(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId === '') throw invalid('session_id must be a non-empty string', ['session_id']);
+    return this.#request('GET', `/agent/checkout-session/${encodeURIComponent(sessionId)}`);
+  }
+
+  async status() {
+    return this.#request('GET', '/status');
+  }
+
+  async #request(method, path, body) {
+    const headers = { Accept: 'application/json', 'User-Agent': this.userAgent };
+    if (this.token) headers.Authorization = `Bearer ${this.token}`;
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    const init = { method, headers, body: body === undefined ? undefined : JSON.stringify(body) };
+
+    // A POST is never retried: /quote spends a live carrier rating and
+    // /agent/checkout-session opens a session, so a repeat is not free.
+    const attempts = method === 'GET' ? MAX_GET_ATTEMPTS : 1;
+    for (let attempt = 1; ; attempt++) {
+      let response;
+      let text;
+      try {
+        ({ response, text } = await this.#send(this.baseUrl + path, init));
+      } catch (error) {
+        if (attempt < attempts) {
+          await sleep(BACKOFF_MS * attempt);
+          continue;
+        }
+        throw error;
+      }
+      if (response.status >= 500 && attempt < attempts) {
+        await sleep(BACKOFF_MS * attempt);
+        continue;
+      }
+      return parseBody(response, text);
+    }
+  }
+
+  async #send(url, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, { ...init, signal: controller.signal });
+      const text = await response.text();
+      return { response, text };
+    } catch (cause) {
+      const timedOut = cause && cause.name === 'AbortError';
+      const detail = cause && cause.cause && cause.cause.message ? cause.cause.message : cause && cause.message;
+      throw new SmklogError(
+        timedOut ? `Request to ${url} timed out after ${this.timeout} ms` : `Request to ${url} failed: ${detail}`,
+        { status: 0, error: 'network_error', cause },
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+function parseBody(response, text) {
+  let parsed = null;
+  let parsable = text === '';
+  if (text !== '') {
+    try {
+      parsed = JSON.parse(text);
+      parsable = true;
+    } catch {
+      parsable = false;
+    }
+  }
+  if (!response.ok) throw errorFromResponse(response, parsable ? parsed : null, text);
+  if (!parsable) {
+    throw new SmklogError(`HTTP ${response.status} from ${response.url} is not JSON`, {
+      status: response.status,
+      error: 'invalid_response',
+      body: text,
+    });
+  }
+  return parsed;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "smklog",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Official JavaScript client for the SMKlog Quote API: live USPS, UPS, FedEx and DHL parcel rates from a US origin, a checkout handed to a human, and where that checkout stands. No API key.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smklog/smklog-sdk.git",
+    "directory": "javascript"
+  },
+  "homepage": "https://smklog.com/developers/",
+  "bugs": {
+    "email": "info@smklog.com"
+  },
+  "keywords": [
+    "smklog",
+    "shipping",
+    "shipping-rates",
+    "parcel",
+    "postage",
+    "label",
+    "usps",
+    "ups",
+    "fedex",
+    "dhl",
+    "quote",
+    "checkout",
+    "api-client",
+    "sdk"
+  ]
+}