feat: notification methods on PlatformClient, backend types via submodule

[ABujalance]

Do not merge yet. The submodule is pinned to the backend's feature/notification-dtos branch (backend-api#321). Once that merges, yarn types:update moves the pin and the branch in .gitmodules changes to main.

Summary

Notification methods on PlatformClient, and a submodule so the types come from the backend instead of being hand-copied.

Nothing new on the API side. Apps already call the platform as the signed-in user — AppIframe posts them the JWT — so these are client methods over endpoints that are already live.

• getNotifications({ cursor, limit })
• getUnreadNotificationCount()
• markNotificationsRead(ids)
• markAllNotificationsRead()
• getNotificationSubscriptions()
• unsubscribeFromAutomation(hookId)

Why a submodule and not another copy

Every file in src/types is a hand-maintained copy of a backend type. That is why base.ts has to declare export type ObjectId = string and hope it stays true — and it mostly is true, because JSON has no ObjectId, but nothing enforces it.

The backend now has src/common/dto: wire shapes with string ids and ISO timestamps, importing nothing from mongodb, so they compile in a browser build unchanged. src/types/notifications.ts re-exports from there. If the backend changes the contract, this package stops compiling instead of drifting quietly.

Sparse-checked-out to that one directory: 37 files on disk rather than the whole backend repo.

The update command

yarn types:update moves the pin to the tip of the tracked branch and re-applies the sparse checkout. yarn types:init just re-applies the sparse checkout without moving anything, which is what CI runs.

Deliberately a command and not a postinstall hook. An install that silently moved the pin would break a build with no commit explaining why, on someone else's machine, mid-task. The pin moves when someone decides it should.

One thing worth reviewing carefully

The build succeeded while producing a broken package, and it took building and installing it to notice.

vite-plugin-dts only emits declarations for files it is told to include. The re-export compiled fine, yarn build was green, and the published dist/src/types/notifications.d.ts re-exported from ../../vendor/... — a path that does not exist in dist. A consumer would have installed the package and found NotificationDto unresolvable.

Fixed by adding the vendored path to both tsconfig.json and the dts plugin's include, so declarations emit to dist/vendor/... where the relative path resolves. Verified by building the package, copying dist into a scratch project and typechecking a consumer against it:

import type { NotificationDto } from './pkg/dist/index';
const n: NotificationDto = { /* ... */ };   // resolves, strict mode, no errors

Worth knowing because it will apply to anything else vendored this way.

Verification

yarn build green, npx vitest run green (5 files, 69 tests, 10 new), eslint clean. The new tests cover each method's path, method and body, that the opaque cursor round-trips unmangled, that the unread count is unwrapped to a number, and that the bearer token is sent on notification routes.

CI now checks out with submodules: true and runs yarn types:init before install, on both the build and release workflows.

[smoratino-apogea]

This makes the repo impossible to build without access to the private backend.
On a clean clone:

src/types/notifications.ts(18,8): error TS2307: Cannot find module
'../../vendor/backend-api/src/common/dto/notifications.dto'

and yarn build runs tsc, so the whole thing falls over. Since this repo is public, people outside the org and PRs from forks, which have no secrets can't build it.

What about splitting this part into its own PR? The REST methods look good and could go in on their own already.

[smoratino-apogea]

I don't think the fallback is reachable: this step has no continue-on-error, so if the secrets are missing the job dies here and the || on line 35 never gets evaluated. And since the same step is in release.yml, publishing would be blocked too.

Adding continue-on-error: true here would make it behave the way the comment above describes.

[smoratino-apogea]

Adding vendor/ to the dts include reshuffles the published .d.ts: on main it's dist/{core,types,...}, here it's dist/src/... + dist/vendor/... with index.d.ts as a stub.

The types entrypoint still resolves, but any deep import breaks and the changeset is marked minor.