pk-shared

README

pk-shared

Part of PlatformKit — the open-source Go backend for multi-tenant SaaS.

Depends on. Nothing else in PlatformKit. It is a leaf of the dependency graph, so anything in the family can depend on it without creating a cycle.

pk-shared is the deliberately small, provider-neutral contract library for the OSS PlatformKit family (pk-core, pk-design, pk-modules, pk-apps). It owns only the cross-repo vocabulary — the JSON API wire contract, application composition descriptors, neutral flow definitions, and canonical URL path segments — that cannot cleanly belong to a single owning repo. If a contract has a natural home, it lives there instead of becoming ambient shared state.

Install

go get github.com/septagon-oss/pk-shared@v0.5.0

Usage

package main

import (
	"fmt"

	"github.com/septagon-oss/pk-shared/pkg/composition"
)

func main() {
	app := &composition.Application{
		APIVersion: composition.APIVersionV1,
		Kind:       composition.KindApplication,
		Metadata:   composition.AppMetadata{Name: "demo"},
		Spec: composition.ApplicationSpec{
			Modules: []composition.ModuleRef{
				{Name: "user_management", Enabled: true},
			},
		},
	}

	catalog := []composition.ModuleCatalogEntry{{ID: "user_management"}}
	report := composition.Validate(app, catalog)
	fmt.Println("valid:", report.Valid)
	fmt.Println("enabled:", composition.EnabledModules(app))
}

Current Surface

• pkg/apiwire: the JSON API wire contract (REQ-021) — canonical list-query parameters with legacy aliases and {"data": ...} item/list envelopes shared by pk-client and every conforming server; errors remain RFC 9457 problems
• pkg/composition: application, overlay, and topology-cell descriptors used to compose modules, surfaces, catalogs, and infrastructure blueprints, plus validation and Helm/config export helpers
• pkg/permissiontoken: the canonical, provider-neutral resource:action permission grammar, including the bare * full-access declaration
• pkg/flowdef: neutral reusable flow definitions for UI/API coverage, authoring, and E2E/testkit bridges
• pkg/pathsegment: canonical opaque-ID URL path-segment encoding with fail-closed decoding, so entity identifiers survive any HTTP stack

Verify

make verify   # go test + go vet + staticcheck + race

License

Apache-2.0. See LICENSE.