@datadog/apps-frontend 0.0.1 → 0.0.2

package/dist/src/embedding/react/provider.d.ts

@@ -0,0 +1,8 @@
+/* Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2019-Present Datadog, Inc.
+ */
+
+import type { ComponentType, PropsWithChildren } from 'react';
+/** Owns the shared embedding connection for all descendant Datadog App hooks. */
+export declare const DatadogAppProvider: ComponentType<PropsWithChildren>;

package/dist/src/embedding/react/use-datadog-app-embedding.d.ts

@@ -0,0 +1,29 @@
+/* Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2019-Present Datadog, Inc.
+ */
+
+import type { EmbeddingMetadata } from '../index.js';
+export interface UseDatadogAppEmbeddingOptions {
+    /**
+     * Suspend (throw a promise) while the connection is still settling
+     * (`connecting`/`reconnecting`), and throw an `Error` for a terminal
+     * failure (`rejected`/`closed`) so the nearest error boundary catches it.
+     * Only `connected`/`not-embedded` -- both legitimate states to render
+     * against -- are ever returned. Defaults to `false`.
+     */
+    readonly suspense?: boolean;
+}
+type SettledEmbeddingMetadata = Extract<EmbeddingMetadata, {
+    state: 'connected' | 'not-embedded';
+}>;
+/**
+ * Tracks this app's embedding connection: its lifecycle state, any connection
+ * error, and which product surface the host embedded it into. Must be called
+ * below `DatadogAppProvider`.
+ */
+export declare function useDatadogAppEmbedding(options: Readonly<{
+    suspense: true;
+}>): SettledEmbeddingMetadata;
+export declare function useDatadogAppEmbedding(options?: UseDatadogAppEmbeddingOptions): EmbeddingMetadata;
+export {};

package/dist/src/embedding/types.d.ts

@@ -0,0 +1,351 @@
+/* Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2019-Present Datadog, Inc.
+ */
+
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+export type Unsubscribe = () => void;
+export type Result<TValue, TError> = Readonly<{
+    ok: true;
+    value: TValue;
+}> | Readonly<{
+    ok: false;
+    error: TError;
+}>;
+/**
+ * A synchronous, deterministic, validation-only Standard Schema.
+ *
+ * Both embedding peers validate independently. Schemas must therefore have
+ * identical input/output types and must not coerce or transform accepted
+ * values.
+ */
+export type ValueSchema<TValue> = StandardSchemaV1<TValue, TValue>;
+export type AnySchema = StandardSchemaV1;
+export type InferOf<TSchema extends AnySchema> = StandardSchemaV1.InferOutput<TSchema>;
+export type ValidationOnlySchema<TSchema extends AnySchema> = StandardSchemaV1.InferInput<TSchema> extends StandardSchemaV1.InferOutput<TSchema> ? StandardSchemaV1.InferOutput<TSchema> extends StandardSchemaV1.InferInput<TSchema> ? TSchema : never : never;
+export type ContractVersion = number;
+export interface ValueField<TSchema extends AnySchema> {
+    readonly kind: 'value';
+    readonly schema: ValidationOnlySchema<TSchema>;
+}
+export interface FunctionField<TInputs extends Readonly<Record<string, AnySchema>>, TResult extends AnySchema> {
+    readonly kind: 'function';
+    readonly inputs: {
+        readonly [TName in keyof TInputs]: ValidationOnlySchema<TInputs[TName]>;
+    };
+    readonly result: ValidationOnlySchema<TResult>;
+}
+export type AnyFunctionField = FunctionField<Readonly<Record<string, AnySchema>>, AnySchema>;
+export type AnyField = ValueField<AnySchema> | AnyFunctionField;
+export interface Contract<TFields extends Record<string, AnyField>> {
+    readonly identifier: string;
+    readonly version: ContractVersion;
+    readonly fields: TFields;
+}
+export type AnyContract = Contract<Record<string, AnyField>>;
+export interface LiveValue<TValue> {
+    get(): TValue;
+    subscribe(onChange: () => void): Unsubscribe;
+}
+export interface HostFunctionContext {
+    /**
+     * Aborts once the call is cancelled or its deadline passes. An async
+     * implementation should check or listen for this to stop early. A
+     * *synchronous* implementation has no way to observe it mid-call: JS
+     * can't preempt a running function, so a synchronous handler that blocks
+     * past the deadline still runs to completion and produces its value --
+     * the caller is simply told the call timed out and never sees that
+     * value, rather than the value being prevented from being computed.
+     */
+    readonly signal: AbortSignal;
+}
+export interface HostFunction {
+    invoke(inputs: Readonly<Record<string, unknown>>, context: HostFunctionContext): unknown;
+}
+export type FunctionInputs<TInputs extends Readonly<Record<string, AnySchema>>> = {
+    readonly [TName in keyof TInputs]: InferOf<TInputs[TName]>;
+};
+/** Resolves a contract field to the plain value/callable shape a claimant receives, ignoring subscription. */
+type FieldValue<TField extends AnyField> = TField extends ValueField<infer TSchema> ? InferOf<TSchema> : TField extends FunctionField<infer TInputs, infer TResult> ? (inputs: FunctionInputs<TInputs>) => Promise<InferOf<TResult>> : never;
+type ClaimedField<TField extends AnyField> = TField extends ValueField<infer TSchema> ? LiveValue<InferOf<TSchema>> : FieldValue<TField>;
+/** The live, per-field view of a claim: subscribable `LiveValue`s for value fields, callables for function fields. */
+export type ClaimedFields<TContract extends AnyContract> = {
+    readonly [TKey in keyof TContract['fields']]: ClaimedField<TContract['fields'][TKey]>;
+};
+declare const hostModuleBrand: unique symbol;
+/**
+ * One contract version, live and ready to serve claims. Nominally branded --
+ * `hostModuleBrand` is declared but never exported, so only this package can
+ * produce a `HostModule`, and only through `createHostModule()`. That is what
+ * keeps a host from assembling a module for one hand-picked version: the
+ * single supported way in is to provide an inputs definition, which mints a
+ * module for *every* version that definition still converts to. The brand has
+ * no runtime representation.
+ */
+export interface HostModule {
+    readonly [hostModuleBrand]: true;
+    readonly contract: AnyContract;
+    readonly implementation: Readonly<Record<string, LiveValue<unknown> | HostFunction>>;
+    readonly signal?: AbortSignal;
+}
+export interface Issue {
+    readonly message: string;
+    readonly path: readonly (string | number)[];
+}
+export type AnyError = Readonly<{
+    code: 'ORIGIN_REJECTED';
+    origin: string;
+}> | Readonly<{
+    code: 'APP_PROTOCOL_TOO_OLD';
+    appProtocols: readonly number[];
+    hostProtocols: readonly number[];
+}> | Readonly<{
+    code: 'HOST_PROTOCOL_TOO_OLD';
+    appProtocols: readonly number[];
+    hostProtocols: readonly number[];
+}> | Readonly<{
+    code: 'PROTOCOL_INCOMPATIBLE';
+    appProtocols: readonly number[];
+    hostProtocols: readonly number[];
+}> | Readonly<{
+    code: 'PEER_LACKS_MODULE';
+    identifier: string;
+}> | Readonly<{
+    code: 'APP_MAJOR_TOO_OLD';
+    wanted: ContractVersion;
+    hostVersions: readonly ContractVersion[];
+}> | Readonly<{
+    code: 'HOST_MAJOR_TOO_OLD';
+    wanted: ContractVersion;
+    hostVersions: readonly ContractVersion[];
+}> | Readonly<{
+    code: 'CONTRACT_INCOMPATIBLE';
+    field: string;
+}> | Readonly<{
+    code: 'INVALID_ARGUMENT';
+    issues: readonly Issue[];
+}> | Readonly<{
+    code: 'FUNCTION_FAILED';
+    field: string;
+}> | Readonly<{
+    code: 'INVALID_RESULT';
+    issues: readonly Issue[];
+}> | Readonly<{
+    code: 'TIMED_OUT';
+    timeoutMs: number;
+}> | Readonly<{
+    code: 'TRANSPORT_FAILED';
+    cause: unknown;
+}> | Readonly<{
+    code: 'ABORTED';
+}> | Readonly<{
+    code: 'DISCONNECTED';
+}> | Readonly<{
+    code: 'UNRECOGNIZED';
+    rawCode: string;
+    raw: unknown;
+}>;
+export type ErrorOf<TCode extends AnyError['code']> = Extract<AnyError, {
+    code: TCode;
+}>;
+export type ConnectError = ErrorOf<'ORIGIN_REJECTED' | 'APP_PROTOCOL_TOO_OLD' | 'HOST_PROTOCOL_TOO_OLD' | 'PROTOCOL_INCOMPATIBLE' | 'TIMED_OUT' | 'TRANSPORT_FAILED' | 'ABORTED' | 'DISCONNECTED' | 'UNRECOGNIZED'>;
+export type WireClaimError = ErrorOf<'PEER_LACKS_MODULE' | 'APP_MAJOR_TOO_OLD' | 'HOST_MAJOR_TOO_OLD' | 'CONTRACT_INCOMPATIBLE' | 'INVALID_RESULT' | 'TIMED_OUT' | 'ABORTED' | 'DISCONNECTED' | 'UNRECOGNIZED'>;
+export type WireFunctionError = ErrorOf<'CONTRACT_INCOMPATIBLE' | 'INVALID_ARGUMENT' | 'FUNCTION_FAILED' | 'INVALID_RESULT' | 'TIMED_OUT' | 'ABORTED' | 'DISCONNECTED' | 'UNRECOGNIZED'>;
+export type ClaimInvalidationError = ErrorOf<'INVALID_RESULT' | 'DISCONNECTED' | 'UNRECOGNIZED'>;
+export interface Claimed<TContract extends AnyContract> {
+    readonly fields: ClaimedFields<TContract>;
+    release(): void;
+    onValuesChanged(listener: () => void): Unsubscribe;
+    onInvalidated(listener: (error: ClaimInvalidationError) => void): Unsubscribe;
+}
+export interface ClaimOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface AppConnection {
+    claim<TContract extends AnyContract>(contract: TContract, options?: ClaimOptions): Promise<Result<Claimed<TContract>, WireClaimError>>;
+}
+/**
+ * Identifies which product surface a Datadog App is embedded into (e.g. the
+ * Service Catalog side panel vs. IDP), so an app can render surface-specific
+ * content. Each value matches the `identifier` of the inputs schema that
+ * surface provides -- see `../inputs/schemas`. Sent host-to-app as part of
+ * the embedding connection handshake.
+ */
+/**
+ * Every surface, as a tuple rather than a bare union so it can also serve as a
+ * type: `DatadogAppInputsSchema` defaults its `surfaces` to this, which makes
+ * an IDE print the members in full on hover instead of collapsing them to the
+ * `SurfaceId` alias.
+ */
+export declare const EVERY_SURFACE: readonly [
+    'datadog.idp.homepage',
+    'datadog.idp.service-panel',
+    'datadog.idp.self-service',
+    'datadog.app-builder',
+    'datadog.appsec',
+    'datadog.notebook',
+    'datadog.dashboard'
+];
+/**
+ * Where an app is running. Derived from `EVERY_SURFACE`, so there is one
+ * list, but widened to arbitrary strings: it is inert metadata forwarded to
+ * `listen()`, never used to gate whether embedding connects, so a host is
+ * free to pass a value with no matching surface (e.g. an unmapped view
+ * context) rather than going without one.
+ */
+export type SurfaceId = (typeof EVERY_SURFACE)[number] | (string & {});
+export type AppConnectionState = Readonly<{
+    state: 'connecting';
+    error?: ConnectError;
+}> | Readonly<{
+    state: 'connected';
+    connection: AppConnection;
+    surfaceId?: SurfaceId;
+}> | Readonly<{
+    state: 'reconnecting';
+    lastError: ConnectError;
+}> | Readonly<{
+    state: 'rejected';
+    error: ConnectError;
+}> | Readonly<{
+    state: 'not-embedded';
+}> | Readonly<{
+    state: 'closed';
+}>;
+/**
+ * Public-safe view of `AppConnectionState`: the same lifecycle cases, minus
+ * the raw `AppConnection` a consumer would otherwise have no use for outside
+ * of claiming a contract.
+ */
+export type EmbeddingMetadata = Readonly<{
+    state: 'connecting';
+    error?: ConnectError;
+}> | Readonly<{
+    state: 'connected';
+    surfaceId?: SurfaceId;
+}> | Readonly<{
+    state: 'reconnecting';
+    lastError: ConnectError;
+}> | Readonly<{
+    state: 'rejected';
+    error: ConnectError;
+}> | Readonly<{
+    state: 'not-embedded';
+}> | Readonly<{
+    state: 'closed';
+}>;
+export interface EmbeddingMetadataStore {
+    readonly getSnapshot: () => EmbeddingMetadata;
+    readonly subscribe: (onChange: () => void) => Unsubscribe;
+}
+export interface AppConnectionHandle {
+    getSnapshot(): AppConnectionState;
+    subscribe(onChange: () => void): Unsubscribe;
+    close(): void;
+}
+export interface AppConnectionFactory {
+    connect(): AppConnectionHandle;
+}
+export interface HostListenOptions {
+    /** Security boundary for the app-created bootstrap port. */
+    readonly peer: Readonly<{
+        frame: HTMLIFrameElement;
+        appOrigin: string;
+        /**
+         * Set when the iframe is intentionally configured with an opaque
+         * sandboxed origin, so the host should accept a `"null"` origin from
+         * it in place of an exact match against `appOrigin`.
+         */
+        allowOpaqueOrigin?: boolean;
+    }>;
+    readonly modules: readonly HostModule[];
+    readonly surfaceId?: SurfaceId;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface HostListener {
+    onError(listener: (error: ConnectError) => void): Unsubscribe;
+    close(): void;
+}
+export type EmbeddingError = Readonly<{
+    code: 'TIMED_OUT';
+    message: string;
+    action: 'retry';
+}> | Readonly<{
+    code: 'ORIGIN_REJECTED';
+    message: string;
+    action: 'contact-support';
+}> | Readonly<{
+    code: 'APP_PROTOCOL_TOO_OLD';
+    message: string;
+    action: 'update-app';
+}> | Readonly<{
+    code: 'HOST_PROTOCOL_TOO_OLD' | 'PROTOCOL_INCOMPATIBLE';
+    message: string;
+    action: 'contact-support';
+}> | Readonly<{
+    code: 'CONNECTION_LOST';
+    message: string;
+    action: 'retry';
+}> | Readonly<{
+    code: 'UNKNOWN';
+    message: string;
+    action: 'contact-support';
+}>;
+export type ClaimError = EmbeddingError | Readonly<{
+    code: 'APP_MAJOR_TOO_OLD';
+    action: 'update-app';
+    requestedVersion: ContractVersion;
+    availableVersions: readonly ContractVersion[];
+    message: string;
+}> | Readonly<{
+    code: 'HOST_MAJOR_TOO_OLD';
+    action: 'contact-support';
+    requestedVersion: ContractVersion;
+    availableVersions: readonly ContractVersion[];
+    message: string;
+}>;
+export type ClaimedValues<TContract extends AnyContract> = Readonly<{
+    [TKey in keyof TContract['fields']]: FieldValue<TContract['fields'][TKey]>;
+}>;
+export type ClaimState<TContract extends AnyContract> = Readonly<{
+    status: 'pending';
+}> | Readonly<{
+    status: 'ready';
+    fields: ClaimedValues<TContract>;
+}> | Readonly<{
+    status: 'unavailable';
+}> | Readonly<{
+    status: 'failed';
+    error: ClaimError;
+}>;
+export interface ClaimStore<TContract extends AnyContract> {
+    readonly getSnapshot: () => ClaimState<TContract>;
+    readonly subscribe: (onChange: () => void) => Unsubscribe;
+}
+/** Framework-neutral claim capability consumed by feature modules. */
+export interface AppClaims {
+    getClaim<TContract extends AnyContract>(contract: TContract): ClaimStore<TContract>;
+}
+/** Owns the lifecycle of one concrete embedding implementation. */
+export interface AppEmbedding extends AppClaims {
+    start(): Unsubscribe;
+    getEmbeddingMetadata(): EmbeddingMetadataStore;
+}
+/**
+ * One established connection, owned by the caller that opened it. These say
+ * nothing about which operational protocol produced them, so the connection
+ * lifecycle does not change when a protocol is added or retired.
+ */
+export type ManagedAppConnection = Readonly<{
+    connection: AppConnection;
+    surfaceId?: SurfaceId;
+    closeSignal: AbortSignal;
+    close(): void;
+}>;
+export type ManagedHostConnection = Readonly<{
+    closeSignal: AbortSignal;
+    close(): void;
+}>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datadog/apps-frontend",
-    "version": "0.0.1",
+    "version": "0.0.2",
     "private": false,
     "description": "React inputs for Datadog Apps",
     "homepage": "https://datadoghq.com",
@@ -20,6 +20,14 @@
         ".": {
             "types": "./dist/src/index.d.ts",
             "default": "./dist/src/index.js"
+        },
+        "./embedding": {
+            "types": "./dist/src/embedding/index.d.ts",
+            "default": "./dist/src/embedding/index.js"
+        },
+        "./embedding/react": {
+            "types": "./dist/src/embedding/react/index.d.ts",
+            "default": "./dist/src/embedding/react/index.js"
         }
     },
     "publishConfig": {
@@ -27,6 +35,14 @@
             ".": {
                 "types": "./dist/src/index.d.ts",
                 "default": "./dist/src/index.js"
+            },
+            "./embedding": {
+                "types": "./dist/src/embedding/index.d.ts",
+                "default": "./dist/src/embedding/index.js"
+            },
+            "./embedding/react": {
+                "types": "./dist/src/embedding/react/index.d.ts",
+                "default": "./dist/src/embedding/react/index.js"
             }
         },
         "access": "public"
@@ -37,12 +53,21 @@
         "test-unit": "test-unit:workspace",
         "typecheck": "typecheck:workspace"
     },
-    "dependencies": {},
+    "dependencies": {
+        "@standard-schema/spec": "1.1.0",
+        "penpal": "7.0.6"
+    },
     "devDependencies": {
+        "@testing-library/react": "16.3.0",
         "@types/datadog": "workspace:*",
         "@types/node": "catalog:",
+        "@types/react": "catalog:",
+        "@types/react-dom": "catalog:",
         "esbuild": "0.27.5",
-        "typescript": "patch:typescript%40npm%3A6.0.2#~/.yarn/patches/typescript-npm-6.0.2-no-dts-errors.patch"
+        "react": "catalog:",
+        "react-dom": "catalog:",
+        "typescript": "patch:typescript%40npm%3A6.0.2#~/.yarn/patches/typescript-npm-6.0.2-no-dts-errors.patch",
+        "zod": "4.3.6"
     },
     "peerDependencies": {
         "react": "^18.0.0 || ^19.0.0"