SDKs and snippet · URLCrop

Node / TypeScript

npm i @urlcrop/sdk

import { URLCrop } from '@urlcrop/sdk';
const uc = new URLCrop({ apiKey: process.env.URLCROP_API_KEY! });
for await (const link of uc.links.list({ campaign_id: 'cmp_…' })) console.log(link.short_url, link.clicks);

Retries 429/5xx with backoff, generates idempotency keys, exposes typed errors (PlanLimitError, RateLimitError, …) and uc.webhooks.constructEvent(). Requires Node 18+.

Create a link and handle errors:

import { URLCrop, URLCropError, RateLimitError, PlanLimitError } from '@urlcrop/sdk';

try {
  const link = await uc.links.create({ destination_url: 'https://brand.in/diwali-sale' });
  console.log(link.short_url);
} catch (err) {
  if (err instanceof PlanLimitError) console.error('Plan limit reached');
  else if (err instanceof RateLimitError) console.error('Slow down or retry later');
  else if (err instanceof URLCropError) console.error(err.status, err.code, err.requestId);
  else throw err;
}

Retries 429/5xx and network errors with backoff (up to 3) and generates idempotency keys, reused across retries. A Retry-After above 60 seconds is not waited out: the SDK throws RateLimitError straight away. Requires Node 18+. The client covers links, QR codes, domains, insights, usage, workspace, pages, campaigns, tags, webhooks, members, invitations and billing. Operations that need a dashboard session are not in the SDK.

Verify a webhook in your handler with the raw request body (the secret is shown once when you create the endpoint or rotate it):

const event = uc.webhooks.constructEvent(rawBody, req.headers['urlcrop-signature'] as string, process.env.URLCROP_WEBHOOK_SECRET!);

It throws SignatureVerificationError on a bad signature. With a uc_test_ key uc.isTest is true and everything runs in test mode (section 10).

Browser snippet

<script async src="https://static.urlcrop.com/uc.js" data-key="uc_pub_…"></script>

Use a publishable key (uc_pub_…), never a secret key. Send visitors to URLs with ?ucid= and report results with urlcrop.track('lead', { external_id: 'lead_8812' }) and urlcrop.identify({ … }); calls made before the script loads are queued. Pin a version with https://static.urlcrop.com/uc/v1.2.0.js (immutable, cached for a year; the unversioned /uc.js is cached for an hour). If you use a Content Security Policy, allow script-src https://static.urlcrop.com. The snippet is under 2 KB gzipped, has no dependencies and needs no eval. Conversion collection (POST /v1/collect) is part of the Phase 2 Convert release.

PHP and Python SDKs are planned after the Partners release; until then use any HTTP client with the reference above.