@xapps-platform/xapp-manifest 0.1.1

package/README.md

@@ -0,0 +1,73 @@
+# `@xapps-platform/xapp-manifest`
+
+Shared Xapp manifest schema, types, and structural validator.
+
+## Install
+
+```bash
+npm install @xapps-platform/xapp-manifest
+```
+
+## Purpose
+
+Use this package when you need manifest parsing and validation without pulling in the broader backend/runtime SDK surface.
+
+It is the direct public home for:
+
+- `xappManifestJsonSchema`
+- `parseXappManifest(...)`
+- manifest-facing TypeScript types such as `XappManifest`
+
+## What moved here
+
+This package now owns the shared manifest contract that was previously implemented only in the core validator.
+
+That shared surface includes:
+
+- JSON schema validation
+- structural manifest normalization/parsing
+- shared governance checks for hook/notification/invoice/subject-profile manifest sections
+- structured warnings for unreferenced definitions/templates
+
+## What stayed in core
+
+Gateway/runtime-only behavior still stays in core API code.
+
+The current core wrapper in `src/validation/xappManifest.ts` exists only to:
+
+- reuse this shared validator
+- map shared warnings into gateway logger output
+
+## Minimal usage
+
+```ts
+import { parseXappManifest, xappManifestJsonSchema } from "@xapps-platform/xapp-manifest";
+
+const manifest = parseXappManifest({
+  name: "Example Xapp",
+  slug: "example-xapp",
+  version: "1.0.0",
+  tools: [],
+  widgets: [],
+});
+
+console.log(manifest.slug);
+console.log(xappManifestJsonSchema.type);
+```
+
+## Relation to other packages
+
+- `@xapps-platform/server-sdk` re-exports this package for convenience in backend-oriented code.
+- `@xapps/cli` uses this validator through `@xapps-platform/server-sdk` so current CLI publish flows stay non-breaking.
+
+## Build
+
+```bash
+npm run build --workspace packages/xapp-manifest
+```
+
+## Smoke
+
+```bash
+npm run smoke --workspace packages/xapp-manifest
+```

package/dist/hookContracts.d.ts

@@ -0,0 +1,22 @@
+export declare const CURRENT_GUARD_TRIGGERS: readonly ["before:installation_create", "before:widget_load", "before:session_open", "before:thread_create", "before:tool_run", "after:install", "after:link_complete", "before:link_revoke", "before:uninstall", "after:tool_complete", "after:uninstall"];
+export declare const RESERVED_POST_ACTION_GUARD_TRIGGERS: readonly ["after:payment_completed", "after:payment_failed", "after:request_created", "after:response_ready", "after:response_finalized"];
+export declare const ALL_KNOWN_GUARD_TRIGGERS: readonly ["before:installation_create", "before:widget_load", "before:session_open", "before:thread_create", "before:tool_run", "after:install", "after:link_complete", "before:link_revoke", "before:uninstall", "after:tool_complete", "after:uninstall", "after:payment_completed", "after:payment_failed", "after:request_created", "after:response_ready", "after:response_finalized"];
+export declare const HOOK_EFFECT_KINDS: readonly ["policy", "invoice", "notification", "integration_call"];
+export declare const HOOK_EXECUTION_MODES: readonly ["gateway_managed", "tenant_managed", "publisher_managed", "gateway_delegated"];
+export declare const HOOK_PROVIDER_SCOPES: readonly ["gateway", "tenant", "publisher"];
+export declare const HOOK_FAILURE_POLICIES: readonly ["fail_closed", "fail_open", "audit_only", "retry"];
+export declare const HOOK_IDEMPOTENCY_SCOPES: readonly ["none", "request", "request_response", "payment_session", "payment_receipt", "response_version"];
+export type CurrentGuardTrigger = (typeof CURRENT_GUARD_TRIGGERS)[number];
+export type ReservedPostActionGuardTrigger = (typeof RESERVED_POST_ACTION_GUARD_TRIGGERS)[number];
+export type KnownGuardTrigger = (typeof ALL_KNOWN_GUARD_TRIGGERS)[number];
+export type HookEffectKind = (typeof HOOK_EFFECT_KINDS)[number];
+export type HookExecutionMode = (typeof HOOK_EXECUTION_MODES)[number];
+export type HookProviderScope = (typeof HOOK_PROVIDER_SCOPES)[number];
+export type HookFailurePolicy = (typeof HOOK_FAILURE_POLICIES)[number];
+export type HookIdempotencyScope = (typeof HOOK_IDEMPOTENCY_SCOPES)[number];
+export declare function normalizeHookEffectKind(value: unknown): HookEffectKind | null;
+export declare function normalizeHookExecutionMode(value: unknown): HookExecutionMode | null;
+export declare function normalizeHookProviderScope(value: unknown): HookProviderScope | null;
+export declare function normalizeHookFailurePolicy(value: unknown): HookFailurePolicy | null;
+export declare function normalizeHookIdempotencyScope(value: unknown): HookIdempotencyScope | null;
+//# sourceMappingURL=hookContracts.d.ts.map

package/dist/hookContracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hookContracts.d.ts","sourceRoot":"","sources":["../src/hookContracts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,6PAYzB,CAAC;AAEX,eAAO,MAAM,mCAAmC,2IAMtC,CAAC;AAEX,eAAO,MAAM,wBAAwB,6XAG3B,CAAC;AAEX,eAAO,MAAM,iBAAiB,oEAAqE,CAAC;AACpG,eAAO,MAAM,oBAAoB,0FAKvB,CAAC;AACX,eAAO,MAAM,oBAAoB,6CAA8C,CAAC;AAChF,eAAO,MAAM,qBAAqB,8DAA+D,CAAC;AAClG,eAAO,MAAM,uBAAuB,4GAO1B,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1E,MAAM,MAAM,8BAA8B,GAAG,CAAC,OAAO,mCAAmC,CAAC,CAAC,MAAM,CAAC,CAAC;AAClG,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1E,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAChE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AACvE,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAO7E;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAOnF;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAOnF;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAOnF;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAOzF"}

package/dist/hookRegistry.d.ts

@@ -0,0 +1,14 @@
+import { type CurrentGuardTrigger, type HookEffectKind, type HookFailurePolicy, type KnownGuardTrigger } from "./hookContracts.js";
+export type HookRegistryEntry = {
+    trigger: KnownGuardTrigger;
+    implemented: boolean;
+    blockingDefault: boolean;
+    allowedEffectKinds: HookEffectKind[];
+    allowsDelegatedExecution: boolean;
+    auditCategory: "guard_policy" | "lifecycle" | "payment" | "request" | "response";
+    notes?: string;
+};
+export declare function getHookRegistryEntry(trigger: string): HookRegistryEntry | null;
+export declare function getDefaultFailurePolicyForEffectKind(effectKind: HookEffectKind): HookFailurePolicy;
+export declare function isImplementedHookTrigger(trigger: string): trigger is CurrentGuardTrigger;
+//# sourceMappingURL=hookRegistry.d.ts.map

package/dist/hookRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hookRegistry.d.ts","sourceRoot":"","sources":["../src/hookRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,cAAc,EAAE,CAAC;IACrC,wBAAwB,EAAE,OAAO,CAAC;IAClC,aAAa,EAAE,cAAc,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAuBF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAI9E;AAED,wBAAgB,oCAAoC,CAClD,UAAU,EAAE,cAAc,GACzB,iBAAiB,CAKnB;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI,mBAAmB,CAGxF"}

package/dist/hookResolution.d.ts

@@ -0,0 +1,23 @@
+import { type HookEffectKind, type HookExecutionMode, type HookFailurePolicy, type HookIdempotencyScope, type HookProviderScope } from "./hookContracts.js";
+import { type HookRegistryEntry } from "./hookRegistry.js";
+export type HookResolutionInput = {
+    slug: string;
+    trigger: string;
+    config?: Record<string, unknown> | null;
+};
+export type NormalizedHookGuardConfig = {
+    effectKind: HookEffectKind;
+    executionMode: HookExecutionMode | null;
+    providerScope: HookProviderScope | null;
+    failurePolicy: HookFailurePolicy;
+    idempotencyScope: HookIdempotencyScope | null;
+    providerKey: string | null;
+};
+export type ResolvedHookGuardSemantics = {
+    slug: string;
+    trigger: string;
+    hook: HookRegistryEntry | null;
+    config: NormalizedHookGuardConfig;
+};
+export declare function normalizeHookGuardConfig(input: HookResolutionInput): ResolvedHookGuardSemantics;
+//# sourceMappingURL=hookResolution.d.ts.map

package/dist/hookResolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hookResolution.d.ts","sourceRoot":"","sources":["../src/hookResolution.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAA8D,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEvH,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,UAAU,EAAE,cAAc,CAAC;IAC3B,aAAa,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACxC,aAAa,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACxC,aAAa,EAAE,iBAAiB,CAAC;IACjC,gBAAgB,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC9C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,yBAAyB,CAAC;CACnC,CAAC;AAWF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,mBAAmB,GAAG,0BAA0B,CAiC/F"}