npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@cutoptim/engine

v1.9.0

Published

Official client for the CutOptim Engine API — cutting optimization (2D panels, 1D linear, timber, true-shape nesting) over HTTPS.

Readme


Why this SDK

  • Typed from the contract. Every request and response type is generated from the OpenAPI 3.1 document — your editor knows every field, and its tooltip is the reference text.
  • Zero dependencies. The built-in fetch and Web Crypto: Node 18+, Deno, Bun, edge runtimes and the browser.
  • Retries that never cost twice. Every optimize call carries an Idempotency-Key; a retried call returns the stored answer instead of a second charge.
  • Async jobs without the boilerplate. waitForJob() polls the max engine for you — or let a webhook tell you.
  • Webhook verification built in. verifyWebhook() checks the signature on the raw body, with the replay window and secret rotation handled.

Install

npm install @cutoptim/engine

A free test key (co_test_…, never billed) is enough to build the whole integration — create one on your dashboard.

Quickstart

import { CutOptim } from '@cutoptim/engine';

const client = new CutOptim({ apiKey: process.env.CUTOPTIM_KEY });

const plan = await client.optimize2d({
  parts: [
    { name: 'Side', w: 720, h: 560, qty: 2 },
    { name: 'Shelf', w: 764, h: 540, qty: 3, rotatable: false },
  ],
  stock: [{ w: 2800, h: 2070, price: 48 }],
  options: { kerf: 4 },
});

if (!CutOptim.isJobAccepted(plan)) {
  console.log(`${plan.metrics.sheetCount} sheet(s), ${plan.metrics.yieldPct}% yield`);
  for (const sheet of plan.sheets) {
    for (const p of sheet.parts) console.log(p.name, p.x, p.y, p.w, p.h, p.rotated ? '↻' : '');
  }
}

The same input always returns the same plan — cache it, test against it, quote from it.

Every mode

// 1D linear — bars, profiles, tubes
const bars = await client.optimize1d({
  parts: [{ name: 'Rail', length: 1200, qty: 6 }],
  stock: [{ length: 6000 }],
});
console.log(bars.metrics.rodCount, bars.metrics.yieldPct);

// Timber — lengths cut from beams of a given cross-section (sw × sh)
const timber = await client.optimizeWood({
  parts: [{ name: 'Joist', sw: 45, sh: 145, length: 3600, qty: 4 }],
  stock: [{ sw: 45, sh: 145, length: 4800 }],
});

// True-shape nesting — polygons (or SVG/DXF sources) on sheets
const nest = await client.optimizeNest({
  parts: [{ name: 'Bracket', polygon: [[0, 0], [120, 0], [120, 40], [40, 120], [0, 120]], qty: 10 }],
  stock: [{ w: 1000, h: 500 }],
});
if (!CutOptim.isJobAccepted(nest)) console.log(nest.metrics.sheetCount, nest.metrics.density);

Check a request without spending a call — the validate endpoints need no key and give the same verdict:

const check = await new CutOptim().validate2d(request); // { valid: true, warnings: [...] } or a typed 400

Async max jobs

engine: "max" searches harder (seconds to a minute) and answers 202 with a job id instead of a plan:

const accepted = await client.optimize2d({ ...request, engine: 'max' });
if (CutOptim.isJobAccepted(accepted)) {
  const job = await client.waitForJob(accepted.jobId, { timeoutMs: 5 * 60_000 }); // polls GET /v1/jobs/{id}, no quota
  if (job.status === 'succeeded') console.log(job.result);
}

Webhooks

Instead of polling, register an endpoint on your dashboard and receive a signed POST (job.succeeded / job.failed) when a max job finishes. Verify it on the raw body:

// Express
import express from 'express';
import { verifyWebhook } from '@cutoptim/engine';

app.post('/cutoptim/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const ok = await verifyWebhook(req.body, req.get('CutOptim-Signature'), process.env.CUTOPTIM_WEBHOOK_SECRET!);
  if (!ok) return res.sendStatus(400);
  res.sendStatus(204);                     // answer within 10 s, then do the work
  const event = JSON.parse(req.body.toString('utf8'));
  // deduplicate on event.id — delivery is at least once
});
// Next.js route handler / any Web-standard runtime
export async function POST(request: Request) {
  const raw = await request.text();
  if (!(await verifyWebhook(raw, request.headers.get('CutOptim-Signature'), process.env.CUTOPTIM_WEBHOOK_SECRET!))) {
    return new Response(null, { status: 400 });
  }
  const event = JSON.parse(raw);           // { id, type, created, env, data: { jobId, mode, engine, status } }
  return new Response(null, { status: 204 });
}

During a secret rotation both secrets sign for 24 hours — pass both: verifyWebhook(raw, header, [newSecret, oldSecret]).

Retries and idempotency

| Situation | What the client does | |---|---| | 429 busy, 503, network error | retries (2× by default), waiting Retry-After when the API sends it | | 409 idempotency_in_progress | retries — the first request is still running; the retry receives its answer | | any optimize call | sends an Idempotency-Key (a fresh UUID, or yours) — the same key on every retry |

Pass your own key to make retries safe across process restarts too:

await client.optimizeNest(request, { idempotencyKey: `order-${orderId}` });

Within 24 hours the same key and request return the stored answer — not charged again, and a max job is not queued twice.

Errors

Any non-2xx answer throws a CutOptimError:

import { CutOptimError } from '@cutoptim/engine';

try {
  await client.optimize2d(request);
} catch (e) {
  if (e instanceof CutOptimError) {
    console.log(e.status, e.code, e.details, e.retryAfter); // branch on e.code, never on e.message
  }
}

| code | Status | Meaning | |---|---|---| | invalid_request | 400 | the request is wrong — details.path names the field; never charged | | unauthorized | 401 | missing or unknown API key | | quota_exceeded | 402 | the account's monthly quota is used up — retryAfter counts to the reset | | key_revoked | 403 | the key is revoked, or the API subscription is not active | | idempotency_conflict | 409 | the key was used for a different request — use a new key | | too_large | 413 | an input cap was exceeded (parts, rows, body size) | | busy | 429 | at capacity right now — retried automatically | | service_unavailable | 503 | an engine is not available on this deployment | | solve_timeout | 504 | the nesting solve ran out of time | | timeout | — | waitForJob() gave up waiting (the job keeps running) |

The full list, with what to do for each, is on the errors page.

Configuration

new CutOptim({
  apiKey: 'co_live_…',                   // not needed for health() and validate*()
  baseUrl: 'https://api.cutoptim.com',   // default
  maxRetries: 2,                         // 429 / 503 / 409 in-progress / network errors
  timeoutMs: 30_000,                     // per request
  fetch: customFetch,                    // optional: your own fetch implementation
});

API coverage

| Method | Endpoint | Quota | |---|---|---| | optimize2d(req, opts?) | POST /v1/optimize/2d | 1 call | | optimize1d(req, opts?) | POST /v1/optimize/1d | 1 call | | optimizeWood(req, opts?) | POST /v1/optimize/wood | 1 call | | optimizeNest(req, opts?) | POST /v1/optimize/nest | 1 call | | validate2d · validate1d · validateWood · validateNest | POST /v1/validate/* | free, no key | | importNest(req) | POST /v1/import/nest | free (key required) | | getJob(id) · waitForJob(id) | GET /v1/jobs/{id} | free | | usage() | GET /v1/usage | free | | health() | GET /v1/health | free, no key |

Versioning

The SDK follows semver. The API is v1 and only grows within it: a new field, endpoint or option arrives as a minor SDK release with the regenerated types; nothing you use today is removed or narrowed. See versioning and stability and the API changelog (also as RSS).

Support

This repository is published from the CutOptim monorepo; pull requests are welcome and applied upstream.

License

MIT © CutOptim