Migrate from v1.x to v2.0

Migration checklist

1. Update the SDK package: pip install --upgrade caseforge-sdk or npm install @caseforge/sdk@2.
2. Update exception import paths — CaseForgeAPIError → APIError.
3. Update the case.type field access to case.case_type (Python) or case.caseType (Node.js).
4. Replace cases.fetch() calls with cases.get().
5. Update code that treats cases.list() as a plain list — it now returns an iterable.
6. Switch to OAuth 2.0 client credentials for production deployments (recommended, not required).
7. Test all case creation, update, and close flows in Sandbox.
8. Deploy to production.

Change 1 — Exception names

All exception class names have been simplified. The CaseForge prefix has been dropped. The module import path is unchanged.

Python

from caseforge.exceptions import (
    CaseForgeAPIError,
    CaseForgeRateLimitError,
    CaseForgeNotFoundError,
)

try:
    case = client.cases.get("case_abc")
except CaseForgeNotFoundError as e:
    ...
except CaseForgeAPIError as e:
    ...

from caseforge.exceptions import (
    APIError,
    RateLimitError,
    NotFoundError,
)

try:
    case = client.cases.get("case_abc")
except NotFoundError as e:
    ...
except APIError as e:
    ...

Node.js

import {
  CaseForgeAPIError,
  CaseForgeRateLimitError,
  CaseForgeNotFoundError,
} from '@caseforge/sdk';

try {
  ...
} catch (e) {
  if (e instanceof CaseForgeNotFoundError) {...}
}

import {
  APIError,
  RateLimitError,
  NotFoundError,
} from '@caseforge/sdk';

try {
  ...
} catch (e) {
  if (e instanceof NotFoundError) {...}
}

Change 2 — Case type field renamed

The type attribute on case objects is renamed to case_type (Python) / caseType (Node.js). This avoids shadowing Python's built-in type() function and improves clarity.

case = client.cases.get("case_abc")
print(case.type)  # transaction_monitoring

case = client.cases.get("case_abc")
print(case.case_type)  # transaction_monitoring

const c = await client.cases.get('case_abc');
console.log(c.type);  // transaction_monitoring

const c = await client.cases.get('case_abc');
console.log(c.caseType);  // transaction_monitoring

Change 3 — cases.fetch() removed

cases.fetch(), deprecated in v1.3, is removed in v2.0. Replace all calls with cases.get(). The signature is identical.

case = client.cases.fetch("case_abc")

case = client.cases.get("case_abc")

Change 4 — cases.list() returns an iterable

cases.list() now returns a lazy-paginating CasePage object instead of a plain list. In most situations the behavior is identical — you can iterate over it with a for loop. If your code accesses items by index or calls len(), wrap the result.

cases = client.cases.list(status="open")
first = cases[0]           # worked in v1.x
total = len(cases)         # worked in v1.x

cases = list(client.cases.list(status="open"))
first = cases[0]           # works after list() conversion
total = len(cases)         # works after list() conversion

Validate your migration

Run the following commands to confirm your integration works correctly against the Sandbox API after upgrading:

# Set a Sandbox key (prefix cf_sand_)
export CASEFORGE_API_KEY=cf_sand_your_key_here

# Run your test suite
pytest tests/integration/ -v

# Or run a quick smoke test
python -c "
import caseforge
c = caseforge.Client()
case = c.cases.create(subject_id='test_subj', case_type='transaction_monitoring', priority='low', summary='Migration smoke test')
print('Created:', case.id, case.case_type, case.status)
c.cases.update(case.id, status='closed', resolution='false_positive')
print('Closed OK')
"