[ImriKochWix]

Note

Description

Follow-up to #679: the session upload (POST /api/apps/{app_id}/imported/session-imports) now sends an Idempotency-Key header, which the backend accepts per the API standard for public POSTs (base44-dev/apper#34732). uploadSession mints one randomUUID() per base44 sessions import run, before any attempt, so a retry within the run gets the first response back instead of creating a second Base Code branch. The new 409 idempotency_key_in_use code is mapped to a plain, agent-relayable message.

Related Issue

Follow-up to #679 (review comment). Backend counterpart: base44-dev/apper#34732.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• core/session-import/api.ts: generate one randomUUID() per run in uploadSession and send it as Idempotency-Key on both auth paths — the bare ky call that uses a b44imp_ import key and the getAppClient() call that uses the stored login.
• core/session-import/api.ts: messageFor maps 409 idempotency_key_in_use to "An import of this session is still running. Wait a moment and try again." (idempotency_key_mismatch deliberately keeps the server message — it cannot happen with one key per run.)
• tests/cli/sessions_import.spec.ts: the upload mock now records the idempotency-key request header; a new test asserts both runs send a UUID and that the two keys differ; idempotency_key_in_use is added to the error-message table.
• docs/commands.md: new Idempotency-Key bullet under sessions import.
• CHANGELOG.md: the unreleased sessions import entry notes that each upload carries an Idempotency-Key, so a retry never creates a second branch.

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated docs/ (AGENTS.md) if I made architectural changes

Additional Notes

The key is created once per run rather than per attempt — that is what makes a retry idempotent — and is never reused across runs, so a deliberate second sessions import still creates its own branch. The header is additive: an older backend that ignores it behaves exactly as before. The PR's own test plan reports 29 passing tests plus bun run lint, typecheck and knip; that run was not reproduced in this environment.

---

_{🤖 Generated by Claude | 2026-10-28 12:13 UTC | f59ec4e}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.2.3-pr.682.9217d4b

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.2.3-pr.682.9217d4b"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.2.3-pr.682.9217d4b"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.2.3-pr.682.9217d4b
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}