deriveIdempotencyKey — @gj-kit/toss-payments

A public function from @gj-kit/toss-payments/server. The signature below is taken directly from the 0.6.1 release declaration.

Verified import example

import { deriveIdempotencyKey } from '@gj-kit/toss-payments/server';

Signature, parameters, and return type

/**
 * Deterministically derives an `Idempotency-Key` from a logical operation identity.
 *
 * Format: `<operation>:<part>:<part>…` (segments joined by `:`; with no `parts` the key is just
 * `<operation>`), plus `#<attempt>` when `attempt` is given. Example:
 * `subscription_renewal:sub_01:1756652400000` and, for a new attempt,
 * `subscription_renewal:sub_01:1756652400000#7c9e…`. The same input always yields the same key,
 * so a crash-recovered worker reproduces the key it submitted before and gets Toss's replay
 * instead of a second execution.
 *
 * **The encoding is injective — distinct inputs never derive the same key.** Every segment
 * (`operation`, each element of `parts`, `attempt`) must be non-empty (`reason: 'empty'`) and
 * must consist of visible ASCII **excluding** the two delimiters `:` and `#`
 * (`reason: 'bad-charset'`). Because no segment can contain a delimiter, a key contains `#`
 * exactly once iff an attempt was given, and the prefix splits on `:` back into exactly
 * `operation` + `parts`. Underscores, dots, `@`, `=`, `-` and the like are fine, so the ids the
 * library already validates (`orderId`, `customerKey`, `cancelRequestId`, UUIDs, epoch strings)
 * all pass unchanged; ISO timestamps with `:` do not — use an epoch or a date-only marker.
 *
 * The assembled key then runs through the public {@link idempotencyKey} parser so the provider
 * length limit (1–300 chars, otherwise 400 `INVALID_IDEMPOTENCY_KEY` — `reason: 'too-long'`) and
 * the header-safe charset are enforced in exactly one place: an `Ok` result is always sendable.
 *
 * This is an **explicit** helper: the library never derives keys behind your back, because a
 * deterministic key combined with 4xx replay is a trap the caller must consciously manage with
 * the `attempt` field.
 */
declare function deriveIdempotencyKey(input: DeriveIdempotencyKeyInput): Result<IdempotencyKey, InvalidInput<'idempotencyKey'>>;

This declaration is the source of truth for parameters, optionality, generics, return values, and public union/type contracts. Check the package golden path and this subpath’s import conditions for required environment, permission, and error boundaries before calling it.

Release context

• Package: @gj-kit/toss-payments
• Version: 0.6.1
• Public entry: ./server
• Source: GitHub