feat: TypeScript/npm identity derivation layer

Add DeriveNpmPackage and DeriveTsImport to derive scoped npm package
names (@<org>/<domain>-<name>-<line>-proto) from API identity. Extend
all display, manifest, and unlink surfaces. Promote TypeScript from
Planned to Tier 2 in docs.

Author: daniel-garcia

cmd/apx/commands/unlink.go

@@ -46,6 +46,7 @@ func unlinkAction(cmd *cobra.Command, args []string) error {
 	printGoUnlinkHint(modulePath)
 	printPythonUnlinkHint(modulePath)
 	printJavaUnlinkHint(modulePath)
+	printTsUnlinkHint(modulePath)
 	ui.Success("Unlinked %s - now using released module", modulePath)
 	return nil
 }
@@ -84,3 +85,16 @@ func printJavaUnlinkHint(modulePath string) {
 	coords := config.DeriveMavenCoords(cfg.Org, api)
 	ui.Info("Java: Add %s:<version> to your pom.xml", coords)
 }
+
+func printTsUnlinkHint(modulePath string) {
+	cfg, _ := config.LoadRaw("")
+	if cfg == nil || cfg.Org == "" {
+		return
+	}
+	api, err := config.ParseAPIID(modulePath)
+	if err != nil {
+		return
+	}
+	npmPkg := config.DeriveNpmPackage(cfg.Org, api)
+	ui.Info("TypeScript: Run 'npm install %s' to install the released package", npmPkg)
+}

docs/app-repos/local-development.md

@@ -284,6 +284,46 @@ Key differences from Go and Python:
 
 ---
 
+## TypeScript Development Loop
+
+For TypeScript consumers, APX publishes schema packages to npm with scoped package names:
+
+```bash
+# 1. Add dependency
+apx add proto/payments/ledger/v1@v1.2.3
+
+# 2. Install npm package
+npm install @acme/payments-ledger-v1-proto
+
+# 3. Import in your TypeScript code
+# import { LedgerService } from "@acme/payments-ledger-v1-proto";
+
+# 4. Build and test
+npm run build && npm test
+```
+
+For local development before schemas are released:
+
+```bash
+# Link schema packages locally (planned)
+apx link typescript
+
+# npm resolves from local link
+npm run build
+
+# When ready for released packages
+apx unlink proto/payments/ledger/v1
+npm install @acme/payments-ledger-v1-proto
+```
+
+Key differences from Go and Python:
+
+- **npm-native resolution** -- `npm link` for local dev, npm registry for released packages
+- **Scoped packages** -- all packages use `@<org>/` scope for namespace isolation
+- **`-proto` suffix** -- distinguishes schema packages from application packages
+
+---
+
 ## Adding Dependencies
 
 To use schemas released by other teams:

docs/cli-reference/index.md

@@ -15,7 +15,7 @@ APX commands are organized into logical categories:
 - `apx fetch` - Download toolchain  
 - `apx gen` - Generate code with canonical imports
 - `apx sync` - Update go.work overlays
-- `apx link` - Link Python overlays for local dev
+- `apx link` - Link Python/TypeScript overlays for local dev
 - `apx unlink` - Remove overlays for released APIs
 :::
 
@@ -142,7 +142,14 @@ type Service struct {
 | `proto/users/profile/v1` | `com.<org>.apis` | `users-profile-v1-proto` | `com.<org>.apis.users.profile.v1` |
 | `proto/orders/v1` (3-part) | `com.<org>.apis` | `orders-v1-proto` | `com.<org>.apis.orders.v1` |
 
-**TypeScript** — Planned. npm scope and package name derivation will follow the same deterministic pattern.
+**APX API Path → TypeScript / npm**
+
+| APX API Path | npm Package |
+|---|---|
+| `proto/payments/ledger/v1` | `@<org>/payments-ledger-v1-proto` |
+| `proto/users/profile/v1` | `@<org>/users-profile-v1-proto` |
+| `proto/orders/v1` (3-part) | `@<org>/orders-v1-proto` |
+| `openapi/billing/invoices/v1` | `@<org>/billing-invoices-v1-proto` |
 
 **Local Overlay Paths**
 

docs/concepts/multi-language-strategy.md

@@ -16,13 +16,13 @@ APX provides a symmetric developer experience across languages. The core princip
 
 | Concern | Go | Python | Java | TypeScript |
 |---------|-----|--------|------|------------|
-| Published artifact | Go module | sdist / wheel | Schema zip / jar | Planned |
-| Local overlay | `go.work use` | `pip install -e` | `mvn install:install-file` | Planned |
-| Resolution mechanism | go.work -> go.mod | pkgutil namespace | Maven dependency resolution | Planned |
-| Code generation | `apx gen go` | `apx gen python` | `mvn generate-sources` | Planned |
-| Dev command | `apx sync` | `apx link python` | `apx link java` (planned) | Planned |
-| Unlink hint | `go get ...` | `pip install ...` | pom.xml dependency | Planned |
-| Status | **Tier 1** | **Tier 2** | **Tier 2** | **Planned** |
+| Published artifact | Go module | sdist / wheel | Schema zip / jar | npm package |
+| Local overlay | `go.work use` | `pip install -e` | `mvn install:install-file` | `npm link` |
+| Resolution mechanism | go.work -> go.mod | pkgutil namespace | Maven dependency resolution | npm / workspace |
+| Code generation | `apx gen go` | `apx gen python` | `mvn generate-sources` | `apx gen typescript` (planned) |
+| Dev command | `apx sync` | `apx link python` | `apx link java` (planned) | `apx link typescript` (planned) |
+| Unlink hint | `go get ...` | `pip install ...` | pom.xml dependency | `npm install ...` |
+| Status | **Tier 1** | **Tier 2** | **Tier 2** | **Tier 2** |
 
 ### Tier definitions
 
@@ -42,6 +42,7 @@ Given `org=acme` and API path `proto/payments/ledger/v1`:
 | Python | Import | `acme_apis.payments.ledger.v1` |
 | Java | Maven coords | `com.acme.apis:payments-ledger-v1-proto` |
 | Java | Package | `com.acme.apis.payments.ledger.v1` |
+| TypeScript | npm package | `@acme/payments-ledger-v1-proto` |
 
 ## Go Workflow
 
@@ -70,6 +71,17 @@ Java uses Maven's dependency resolution and code generation phases:
 
 Java developers never interact with Go modules or `go.work`. The Maven coordinate system provides a complete, self-contained experience.
 
-## TypeScript Workflow (Planned)
+## TypeScript Workflow
 
-TypeScript support will follow the same pattern: npm packages as the published artifact, local linking via `npm link` or workspace references, and identity derivation for npm scope/package names.
+TypeScript uses npm packages as the published artifact with scoped package names:
+
+1. **Producer** releases schema artifacts to an npm registry via APX's release pipeline. The npm package name is deterministically derived: `@<org>/<domain>-<name>-<line>-proto`.
+2. **Consumer** installs the package using `npm install @<org>/<domain>-<name>-<line>-proto`.
+3. For local development, `apx link typescript` (planned) links local schema artifacts via `npm link`, allowing resolution without a remote registry.
+4. `apx unlink` removes the local link; `npm install @<org>/<pkg>` adds the released package. Import paths stay the same.
+
+TypeScript developers import generated types directly from the npm package name:
+
+```typescript
+import { LedgerService } from "@acme/payments-ledger-v1-proto";
+```

docs/dependencies/code-generation.md

@@ -10,7 +10,7 @@ apx gen <lang> [path]
 
 The `apx gen` command reads your schemas from `internal/apis/`, generates code using format-specific toolchains (e.g. Buf for protobuf), and writes the output to `internal/gen/<lang>/` with canonical module paths.
 
-**Supported languages:** `go`, `python`, `java`
+**Supported languages:** `go`, `python`, `java`, `typescript`
 
 ---
 
@@ -182,6 +182,46 @@ This mirrors Go's `go.work` overlay and Python's `pip install -e` — same ident
 
 ---
 
+## TypeScript Generation
+
+TypeScript follows the same schema-first pattern. APX derives scoped npm package names from the API identity:
+
+| Component | Pattern | Example |
+|-----------|---------|---------|
+| npm package | `@<org>/<domain>-<name>-<line>-proto` | `@acme/payments-ledger-v1-proto` |
+
+The `-proto` suffix distinguishes schema packages from application packages.
+
+### Consumer Workflow
+
+Install the schema package from npm:
+
+```bash
+npm install @acme/payments-ledger-v1-proto
+```
+
+Import generated types in your TypeScript code:
+
+```typescript
+import { LedgerService } from "@acme/payments-ledger-v1-proto";
+```
+
+### Local Development
+
+For local development before schemas are released, use `apx link typescript` (planned) to create npm links:
+
+```bash
+# Generate and link locally
+apx link typescript   # planned — creates npm link
+
+# npm resolves from local link
+npm run build
+```
+
+This mirrors Go's `go.work`, Python's `pip install -e`, and Java's `~/.m2` — same identity in dev and prod.
+
+---
+
 ## Flags
 
 | Flag | Type | Default | Description |

internal/config/identity.go

@@ -239,6 +239,31 @@ func DeriveJavaPackage(org string, api *APIIdentity) string {
 	return strings.Join(parts, ".")
 }
 
+// DeriveNpmPackage computes the scoped npm package name for an API.
+//
+// Rules:
+//   - Pattern: @<org>/<domain>-<name>-<line>-proto (4-part) or @<org>/<name>-<line>-proto (3-part)
+//   - Lowercased, hyphens join path segments, -proto suffix
+//   - Example: org="acme", proto/payments/ledger/v1 → "@acme/payments-ledger-v1-proto"
+//   - Example: org="acme", proto/orders/v1 (3-part) → "@acme/orders-v1-proto"
+func DeriveNpmPackage(org string, api *APIIdentity) string {
+	scope := strings.ToLower(org)
+	var parts []string
+	if api.Domain != "" {
+		parts = append(parts, strings.ToLower(api.Domain))
+	}
+	parts = append(parts, strings.ToLower(api.Name))
+	parts = append(parts, strings.ToLower(api.Line))
+	parts = append(parts, "proto")
+	return "@" + scope + "/" + strings.Join(parts, "-")
+}
+
+// DeriveTsImport returns the TypeScript import path for an API.
+// In TypeScript, the import path is the npm package name itself.
+func DeriveTsImport(org string, api *APIIdentity) string {
+	return DeriveNpmPackage(org, api)
+}
+
 // pep440PreRe matches SemVer pre-release tags: alpha, beta, rc with optional dot-separator.
 var pep440PreRe = regexp.MustCompile(`-(alpha|beta|rc)\.?(\d+)`)
 
@@ -329,6 +354,10 @@ func DeriveLanguageCoordsWithRoot(sourceRepo, importRoot, org string, api *APIId
 			Module: DeriveMavenCoords(org, api),
 			Import: DeriveJavaPackage(org, api),
 		}
+		coords["typescript"] = LanguageCoords{
+			Module: DeriveNpmPackage(org, api),
+			Import: DeriveTsImport(org, api),
+		}
 	}
 
 	return coords, nil
@@ -410,6 +439,10 @@ func FormatIdentityReport(api *APIIdentity, source *SourceIdentity, release *Rel
 		sb.WriteString(fmt.Sprintf("Java pkg:   %s\n", javaCoords.Import))
 	}
 
+	if tsCoords, ok := langs["typescript"]; ok {
+		sb.WriteString(fmt.Sprintf("npm:        %s\n", tsCoords.Module))
+	}
+
 	return sb.String()
 }
 

internal/config/identity_test.go

@@ -491,19 +491,23 @@ func TestDeriveLanguageCoordsWithRoot(t *testing.T) {
 	assert.Equal(t, "go.acme.dev/apis/proto/payments/ledger", coords["go"].Module)
 	assert.Equal(t, "go.acme.dev/apis/proto/payments/ledger/v1", coords["go"].Import)
 
-	// With org — Python and Java coords are populated.
+	// With org — Python, Java, and TypeScript coords are populated.
 	coords, err = DeriveLanguageCoordsWithRoot("github.com/acme/apis", "", "acme", api)
 	require.NoError(t, err)
 	assert.Equal(t, "acme-payments-ledger-v1", coords["python"].Module)
 	assert.Equal(t, "acme_apis.payments.ledger.v1", coords["python"].Import)
 	assert.Equal(t, "com.acme.apis:payments-ledger-v1-proto", coords["java"].Module)
 	assert.Equal(t, "com.acme.apis.payments.ledger.v1", coords["java"].Import)
+	assert.Equal(t, "@acme/payments-ledger-v1-proto", coords["typescript"].Module)
+	assert.Equal(t, "@acme/payments-ledger-v1-proto", coords["typescript"].Import)
 
-	// Without org — Java coords should be absent.
+	// Without org — Java and TypeScript coords should be absent.
 	coords, err = DeriveLanguageCoordsWithRoot("github.com/acme/apis", "", "", api)
 	require.NoError(t, err)
 	_, hasJava := coords["java"]
 	assert.False(t, hasJava, "java coords should be absent when org is empty")
+	_, hasTs := coords["typescript"]
+	assert.False(t, hasTs, "typescript coords should be absent when org is empty")
 }
 
 func TestBuildIdentityBlockWithRoot(t *testing.T) {
@@ -734,6 +738,57 @@ func TestDeriveJavaPackage(t *testing.T) {
 	}
 }
 
+// ---------------------------------------------------------------------------
+// TypeScript / npm identity derivation
+// ---------------------------------------------------------------------------
+
+func TestDeriveNpmPackage(t *testing.T) {
+	tests := []struct {
+		name string
+		org  string
+		api  *APIIdentity
+		want string
+	}{
+		{
+			name: "4-part with domain",
+			org:  "acme",
+			api:  &APIIdentity{Format: "proto", Domain: "payments", Name: "ledger", Line: "v1"},
+			want: "@acme/payments-ledger-v1-proto",
+		},
+		{
+			name: "3-part no domain",
+			org:  "acme",
+			api:  &APIIdentity{Format: "proto", Domain: "", Name: "orders", Line: "v1"},
+			want: "@acme/orders-v1-proto",
+		},
+		{
+			name: "uppercase org normalized",
+			org:  "ACME",
+			api:  &APIIdentity{Format: "proto", Domain: "Payments", Name: "Ledger", Line: "v2"},
+			want: "@acme/payments-ledger-v2-proto",
+		},
+		{
+			name: "hyphenated org",
+			org:  "acme-corp",
+			api:  &APIIdentity{Format: "proto", Domain: "payments", Name: "ledger", Line: "v1"},
+			want: "@acme-corp/payments-ledger-v1-proto",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, DeriveNpmPackage(tt.org, tt.api))
+		})
+	}
+}
+
+func TestDeriveTsImport(t *testing.T) {
+	// In TypeScript, the import path IS the npm package name.
+	api := &APIIdentity{Format: "proto", Domain: "payments", Name: "ledger", Line: "v1"}
+	npmPkg := DeriveNpmPackage("acme", api)
+	tsImport := DeriveTsImport("acme", api)
+	assert.Equal(t, npmPkg, tsImport)
+}
+
 func TestNormalizePEP440Version(t *testing.T) {
 	tests := []struct {
 		input string

internal/publisher/manifest.go

@@ -47,6 +47,7 @@ type ReleaseManifest struct {
 	PythonImport   string `yaml:"python_import,omitempty" json:"python_import,omitempty"`
 	MavenCoords    string `yaml:"maven_coords,omitempty" json:"maven_coords,omitempty"`
 	JavaPackage    string `yaml:"java_package,omitempty" json:"java_package,omitempty"`
+	NpmPackage     string `yaml:"npm_package,omitempty" json:"npm_package,omitempty"`
 
 	// Tag
 	Tag string `yaml:"tag" json:"tag"`
@@ -138,6 +139,10 @@ func NewManifest(
 		m.JavaPackage = javaCoords.Import
 	}
 
+	if tsCoords, ok := langs["typescript"]; ok {
+		m.NpmPackage = tsCoords.Module
+	}
+
 	return m
 }
 
@@ -233,6 +238,9 @@ func FormatManifestReport(m *ReleaseManifest) string {
 		lines = append(lines, fmt.Sprintf("Maven:       %s", m.MavenCoords))
 		lines = append(lines, fmt.Sprintf("Java pkg:    %s", m.JavaPackage))
 	}
+	if m.NpmPackage != "" {
+		lines = append(lines, fmt.Sprintf("npm:         %s", m.NpmPackage))
+	}
 	if m.PRURL != "" {
 		lines = append(lines, fmt.Sprintf("PR URL:      %s", m.PRURL))
 		if m.PRNumber != 0 {

internal/publisher/manifest_test.go

@@ -233,6 +233,10 @@ func TestNewManifest_WithAllCoords(t *testing.T) {
 			Module: "com.acme.apis:payments-ledger-v1-proto",
 			Import: "com.acme.apis.payments.ledger.v1",
 		},
+		"typescript": {
+			Module: "@acme/payments-ledger-v1-proto",
+			Import: "@acme/payments-ledger-v1-proto",
+		},
 	}
 
 	m := NewManifest(api, source, langs, "v1.0.0", "github.com/acme/apis")
@@ -245,9 +249,13 @@ func TestNewManifest_WithAllCoords(t *testing.T) {
 	assert.Equal(t, "com.acme.apis:payments-ledger-v1-proto", m.MavenCoords)
 	assert.Equal(t, "com.acme.apis.payments.ledger.v1", m.JavaPackage)
 
+	// TypeScript coords
+	assert.Equal(t, "@acme/payments-ledger-v1-proto", m.NpmPackage)
+
 	report := FormatManifestReport(m)
 	assert.Contains(t, report, "Py dist:     acme-payments-ledger-v1")
 	assert.Contains(t, report, "Py import:   acme_apis.payments.ledger.v1")
 	assert.Contains(t, report, "Maven:       com.acme.apis:payments-ledger-v1-proto")
 	assert.Contains(t, report, "Java pkg:    com.acme.apis.payments.ledger.v1")
+	assert.Contains(t, report, "npm:         @acme/payments-ledger-v1-proto")
 }