feat(actor): sync Actor shim with deployed runtime

[ImriKochWix]

What

Aligns the type-only Actor shim (src/actor.ts) with the current Durable Object runtime implementation, which had drifted.

Changes

Removed (no longer exposed by the deployed runtime):

• Conn.userId / Conn.appId / Conn.instanceId
• startLoop() / stopLoop() — the managed ticker is now fully platform-owned

Added (scheduled-wake API):

• handleWake(key) — hook fired when a scheduled timer comes due
• schedule(key, at) — arm a one-shot wake
• cancelSchedule(key) — cancel a pending wake

client, storage, instanceId, broadcast, getConnections, and the ticker (tickIntervalMs/shouldTick) are unchanged.

Verification

npm run build and npm run test:types pass.

🤖 Generated with Claude Code

[claude]

Claude finished @ImriKochWix's task —— View job

---

PR Review: Sync Actor shim with deployed runtime

• Read src/actor.ts and analyze changes
• Review code quality & best practices
• Check for potential bugs/issues
• Assess performance & security
• Evaluate test coverage

Overall this is a clean, well-scoped, type-only change. It's low risk: src/actor.ts is a compile-time shim whose methods either are no-ops or throw at runtime (the real Durable Object implementation is swapped in at deploy). The JSDoc is excellent and the diff faithfully mirrors the stated runtime changes. Approving in spirit — a few small observations below.

Code quality & best practices

• The new handleWake / schedule / cancelSchedule follow the existing convention perfectly (protected, throw-with-consistent-message, thorough JSDoc). Nice consistency.
• Minor inconsistency: handleWake is a silent no-op default ({}), while schedule/cancelSchedule throw "only available inside a deployed actor". That's intentional and correct — handleWake is an override hook (like handleStart), whereas the other two are platform calls. Worth confirming this matches the runtime so a user who calls this.handleWake(...) directly locally doesn't get a surprising silent no-op. Consider a one-line note in the handleWake JSDoc that it's a hook you override, not one you call.

Potential bugs / issues

• Public API removal is a breaking change. Dropping Conn.userId / Conn.appId / Conn.instanceId and startLoop()/stopLoop() will break any existing actor code that referenced them. Since Actor and Conn are part of the public export surface (src/index.ts:123), this warrants a minor/major semver bump and ideally a note in a changelog/migration guide. In particular, losing Conn.userId removes the only per-connection identity — worth calling out the recommended replacement (e.g. pass identity in the connect payload / first message) so users aren't stranded.
• schedule(key, at) accepts number | Date — good. Just confirm the deployed runtime interprets a bare number as epoch ms (as the JSDoc says) and not a relative delay, since that's an easy footgun.

Performance

• N/A — type-only shim, no runtime behavior added here.

Security

• No concerns. Removing userId/appId/instanceId from Conn actually reduces surface area. Note the docstring on client correctly warns it's RLS-gated and unauthenticated — good.

Test coverage

• tests/unit/actors.test.ts covers the client-side actors module (connect/subscribe/send/close/heartbeat), but there are no type-level tests for the Actor/Conn shim itself. The PR body says npm run test:types passes; if that suite exists it'd be valuable to add an assertion that Conn no longer exposes userId/appId/instanceId and that schedule/cancelSchedule/handleWake are present with the right signatures — this locks the shim to the runtime contract and prevents silent future drift (the exact problem this PR is fixing).

Summary

Safe, focused change that reduces drift and API surface. Two things to action before merge:

1. Flag the removals as a breaking change (semver + migration note, esp. the loss of Conn.userId).
2. Optionally add a type-level test asserting the new/removed members to prevent future drift.
   • Branch: feat/update-actor-sdk

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.41-pr.243.98f858c

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

npm i "@base44/sdk@npm:@base44-preview/sdk@0.8.41-pr.243.98f858c"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.41-pr.243.98f858c"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.41-pr.243.98f858c
• 🔗 View this commit on GitHub

---

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