Create a check (BILLABLE + DRAWS FUNDS)

Instructions

Implementation Reference

• src/tools/checks.ts:150-166 (registration)

  The tool 'lob_checks_create' is registered at line 150 in src/tools/checks.ts. It uses checkCommitShape as its input schema and pc.commit as its handler.

  registerTool(server, {
    name: "lob_checks_create",
    annotations: {
      title: "Create a check (BILLABLE + DRAWS FUNDS)",
      ...ToolAnnotationPresets.commit,
    },
    description:
      "Commit a check send. **HIGH IMPACT**: incurs Lob fees AND draws the check `amount` from the " +
      "linked bank account when cashed. Requires a verified bank account ID (`bank_…`). In live mode, " +
      "requires a `confirmation_token` from lob_checks_preview that matches the current payload. " +
      "If LOB_REQUIRE_ELICITATION_FOR_CHECKS_OVER_USD is set and `amount` exceeds it, an elicitation " +
      "form must be confirmed by the user before dispatch.\n\n" +
      "For the bottom of the check page, Lob requires exactly one of `message` (plain text, max 400 " +
      "chars) or `check_bottom` (custom template / HTML / PDF, typically paired with `merge_variables`).",
    inputSchema: checkCommitShape,
    handler: pc.commit,
  });

• src/preview/preview-commit.ts:66-143 (handler)

  The actual handler for lob_checks_create is the 'commit' function returned by buildPreviewCommit (lines 90-142). This is the generic preview/commit factory used by all billable resources including checks.

  return {
    async preview(input) {
      const payload = stripUndefined(input as Record<string, unknown>);
      const previewResponse = await ctx.renderPreview(payload);
      const token = randomUUID();
      const now = Date.now();
      const ttlMs = Math.max(0, ctx.env.confirmationTtlSeconds * 1000);
      const record: PreviewRecord = {
        token,
        toolName: baseName,
        payloadHash: hashPayload(payload),
        payload,
        previewResponse,
        createdAt: now,
        expiresAt: now + ttlMs,
      };
      ctx.tokenStore.put(record);
      return {
        confirmation_token: token,
        expires_at: new Date(record.expiresAt).toISOString(),
        preview: previewResponse,
      };
    },
  
    async commit(input, serverCtx) {
      const inputAny = input as Record<string, unknown>;
      const confirmationToken = inputAny.confirmation_token as string | undefined;
      const explicitKey = inputAny.idempotency_key as string | undefined;
      const { confirmation_token: _t, idempotency_key: _i, ...rest } = inputAny;
      const payload = stripUndefined(rest);
  
      const requireToken =
        ctx.env.requireConfirmation && ctx.env.effectiveCommitMode === "live";
  
      let consumedToken: string | undefined;
      if (confirmationToken) {
        const record = ctx.tokenStore.consume(String(confirmationToken));
        if (!record) {
          throw new LobMcpError(
            LobMcpErrorCodes.TOKEN_NOT_FOUND,
            "Confirmation token not found, expired, or already consumed.",
            `Call ${baseName}_preview again to obtain a fresh token.`,
          );
        }
        if (hashPayload(payload) !== record.payloadHash) {
          throw new LobMcpError(
            LobMcpErrorCodes.TOKEN_PAYLOAD_MISMATCH,
            "Payload differs from the previewed payload.",
            `Call ${baseName}_preview again with the current parameters.`,
          );
        }
        consumedToken = record.token;
      } else if (requireToken) {
        throw new LobMcpError(
          LobMcpErrorCodes.TOKEN_REQUIRED,
          "Live mode requires a confirmation_token from the matching preview tool.",
          `Call ${baseName}_preview with the same parameters to obtain a token.`,
        );
      }
  
      const idempotencyKey =
        explicitKey ??
        (consumedToken ? `lob-mcp-${consumedToken}` : `lob-mcp-${randomUUID()}`);
  
      if (ctx.beforeDispatch) await ctx.beforeDispatch(payload, serverCtx);
  
      const result = await ctx.callCommit(payload, {
        idempotencyKey,
        confirmationToken: consumedToken,
      });
  
      return {
        idempotency_key_used: idempotencyKey,
        confirmation_token_consumed: consumedToken ?? null,
        result,
      };
    },
  };

• src/tools/checks.ts:78-86 (schema)

  Input schema for lob_checks_create, extending checkCreateShape with an optional confirmation_token. checkCreateShape (lines 35-76) includes bank_account, amount, check_number, memo, message, check_bottom, logo, attachment, idempotency_key, and extra fields.

  const checkCommitShape = {
    ...checkCreateShape,
    confirmation_token: z
      .string()
      .optional()
      .describe(
        "Token from lob_checks_preview. Required in live mode (LOB_LIVE_MODE=true).",
      ),
  } as const;

• src/tools/checks.ts:94-136 (helper)

  The buildPreviewCommit call that configures the lob_checks_create tool. It provides: (1) renderPreview — textual summary (no PDF), (2) beforeDispatch — piece counter check + optional elicitation for large amounts, and (3) callCommit — the actual POST /checks API call to Lob.

  const pc = buildPreviewCommit({
    baseName: "lob_checks",
    baseSchema: checkCreateShape,
    ctx: {
      env: lob.env,
      tokenStore,
      renderPreview: async (payload) => ({
        kind: "textual_preview",
        note:
          "Lob does not produce check proofs. This preview confirms validation only — no PDF is rendered. " +
          "The returned confirmation_token binds the payload: committing a different amount or recipient " +
          "will be rejected.",
        bank_account: payload.bank_account,
        amount_usd: payload.amount,
        check_number: payload.check_number ?? "auto-assigned",
        memo: payload.memo,
        design_spec: findSpec("check", "standard"),
      }),
      beforeDispatch: async (payload, serverCtx) => {
        pieceCounter.checkAndReserve(1);
        const threshold = lob.env.requireElicitationForChecksOverUsd;
        const amount = Number(payload.amount);
        if (threshold != null && amount > threshold) {
          await elicitOrFail(serverCtx as { mcpReq?: { elicitInput?: (req: unknown) => Promise<{ action: string; content?: unknown }> } } | undefined, {
            title: "Confirm large check",
            message:
              `About to commit a $${amount.toFixed(2)} check from bank account ${payload.bank_account}. ` +
              "This is irreversible: physical mail will be produced and the amount will be drawn from the linked account when cashed.",
          });
        }
      },
      callCommit: async (payload, { idempotencyKey }) => {
        const { extra, ...rest } = payload as Record<string, unknown>;
        const out = await lob.request({
          method: "POST",
          path: "/checks",
          body: withExtra(rest, extra as Record<string, unknown> | undefined),
          idempotencyKey,
        });
        pieceCounter.record(1);
        return out;
      },
    },

• src/lob/client.ts:43-46 (helper)

  The /checks path is listed as a billable POST path, meaning the Lob client enforces idempotency-key requirements and uses the effective commit mode (live/test) for the request.

  const BILLABLE_POST_PATHS: RegExp[] = [
    /^\/postcards\b/,
    /^\/letters\b/,
    /^\/self_mailers\b/,