# @saif/platform-typespec

A [TypeSpec](https://typespec.io/) library that provides Forge's `SAIF.Platform` conventions:
operation templates, status-code models, auth helpers, and eventing models for describing
service contracts. It compiles to a `.tsp` library (`lib/main.tsp`), not a runtime JS package —
unlike `@saif/platform` and `@saif/platform-react`, its audience is people authoring TypeSpec
service specifications, not app developers importing a JS module.

Forge's `saif-feature-api` and `saif-event-service` templates already generate `main.tsp` files
in this vocabulary (`ResourceRead<T>`, `Scopes<[...]> | Roles<[...]>`, `MockingServer`), so most
consumers meet this library through generated code before they meet it here.

## What it provides

- **Operation templates** (`lib/operations/`) — `ResourceRead`, `ResourceList`, and
  create/update/delete/action variants. The error union varies by template: instance-scoped
  operations that can 404 (`ResourceRead`, `ResourcePartialUpdate`, `ResourceCreateOrReplace`,
  most actions) default to `BadRequest | NotFound | AuthErrors | ServerError`, while
  collection-scoped operations that cannot (`ResourceList`, `ResourceCreate`, `ResourceDelete`)
  default to `BadRequest | AuthErrors | ServerError` (no `NotFound`).
- **Status-code models** (`lib/status-codes/`) — success, redirection, client-error, and
  server-error response models.
- **Auth helpers** (`lib/openapi/`) — `Scopes<>` / `Roles<>` decorators and OAuth/mock-server
  definitions (`oauth.tsp`, `server.tsp`).
- **Eventing** (`lib/eventing/`) — models for event-based service contracts.

## Getting started

Add the package as a dependency and import it from your `.tsp` entry point (this is already
wired for you if your service came from a Forge template):

```tsp
import "@saif/platform-typespec";

using SAIF.Platform;
```

Then use the conventions in your spec, for example:

```tsp
@useAuth(Scopes<["access"]> | Roles<["App.Read"]>)
namespace MyService;

interface Widgets {
  get is ResourceRead<Widget>;
}
```

### Linting

The package ships a [`@typespec/library-linter`](https://typespec.io/) integration
(`src/linter.ts`) that other TypeSpec libraries can compile against to catch usage mistakes.
Opt in by compiling with the linter import, as the `build:tsp` script in this package does:

```sh
tsp compile . --warn-as-error --import @typespec/library-linter --no-emit
```

The linter's rule set is currently empty (`rules: []`) — the integration exists as a
placeholder for future Forge-specific rules (for example, enforcing the standard error unions),
not as an active check today.

## Related documentation

- [`@saif/platform-typespec` reference](../../platform-typespec.md) — full
  library surface: every operation template, status-code model, and auth helper this package
  ships, with usage examples.
- [TypeSpec API Design](../../../build/apis/typespec.md) — designing
  contracts with this library's conventions.
- [TypeSpec reference](../../../build/apis/typespec.md) — why Forge uses TypeSpec and
  links to the upstream language docs.

---

[View source on GitHub](https://github.com/saif-corp/forge/blob/main/src/typescript/packages/saif-platform-typespec/README.md)