@osdk/api 2.8.0-beta.27 → 2.8.0-beta.29

package/build/types/shapes/ShapeDefinition.d.ts

@@ -0,0 +1,167 @@
+import type { WhereClause } from "../aggregate/WhereClause.js";
+import type { ObjectOrInterfaceDefinition, PropertyKeys } from "../ontology/ObjectOrInterface.js";
+import type { CompileTimeMetadata } from "../ontology/ObjectTypeDefinition.js";
+import type { OsdkBase } from "../OsdkBase.js";
+import type { LinkedType, LinkNames } from "../util/LinkUtils.js";
+export declare const SourcePrimaryKeySymbol: unique symbol;
+export declare function isSourcePkSymbol(value: unknown): value is symbol;
+declare const ShapeDefinitionBrand: unique symbol;
+declare const ShapeLinkResultBrand: unique symbol;
+/** Configuration for how a derived link is loaded at runtime. */
+export interface DerivedLinkConfig {
+	defer?: boolean;
+}
+/** The result of calling `ShapeLinkBuilder.as()`, binding a link traversal to a target shape. */
+export interface ShapeLinkResult<TARGET_SHAPE extends ShapeDefinition<ObjectOrInterfaceDefinition>> {
+	readonly __linkResultBrand: typeof ShapeLinkResultBrand;
+	readonly targetShape: TARGET_SHAPE;
+	readonly objectSetDef: ShapeLinkObjectSetDef;
+	readonly config: DerivedLinkConfig;
+}
+/** A single link traversal step in a derived link's object set definition. */
+export interface ShapeLinkSegment {
+	readonly type: "pivotTo";
+	readonly linkName: string;
+	readonly sourceType?: string;
+	readonly targetType?: string;
+}
+/** Sort clause for a derived link's result set. */
+export interface ShapeLinkOrderBy {
+	readonly property: string;
+	readonly direction: "asc" | "desc";
+}
+/** A set operation (union/intersect/subtract) applied to a derived link's object set. */
+export interface ShapeLinkSetOperation {
+	readonly type: "union" | "intersect" | "subtract";
+	readonly other: ShapeLinkObjectSetDef;
+}
+/** Serializable definition of a derived link's object set: link traversals, filters, ordering, and set operations. */
+export interface ShapeLinkObjectSetDef {
+	readonly segments: readonly ShapeLinkSegment[];
+	readonly where?: WhereClause<ObjectOrInterfaceDefinition>;
+	readonly orderBy?: readonly ShapeLinkOrderBy[];
+	readonly limit?: number;
+	readonly distinct?: boolean;
+	readonly setOperations?: readonly ShapeLinkSetOperation[];
+}
+/** How a shape handles null values for a selected property. */
+export type NullabilityOp = {
+	type: "require"
+} | {
+	type: "dropIfNull"
+} | {
+	type: "withDefault"
+	defaultValue: unknown
+} | {
+	type: "withTransform"
+	transform: (value: unknown) => unknown
+} | {
+	type: "select"
+};
+/** Per-property configuration stored in a shape's `__props` map. */
+export interface ShapePropertyConfig {
+	readonly nullabilityOp: NullabilityOp;
+}
+/** A derived link definition stored in a shape's `__derivedLinks` array. */
+export interface ShapeDerivedLinkDef<TARGET_SHAPE extends ShapeDefinition<ObjectOrInterfaceDefinition> = ShapeDefinition<ObjectOrInterfaceDefinition>> {
+	readonly name: string;
+	readonly objectSetDef: ShapeLinkObjectSetDef;
+	readonly targetShape: TARGET_SHAPE;
+	readonly config: DerivedLinkConfig;
+}
+/**
+* Type projection from an OSDK type. `__props` is the single source of truth for property config.
+*
+* @typeParam BASE - The base ObjectTypeDefinition or InterfaceDefinition
+* @typeParam SELECTED_PROPS - Record of selected properties and their transformed types
+* @typeParam DERIVED_LINKS - Record of derived link names to their result types
+*/
+export interface ShapeDefinition<
+	BASE extends ObjectOrInterfaceDefinition,
+	SELECTED_PROPS extends Record<string, unknown> = {},
+	DERIVED_LINKS extends Record<string, ShapeDefinition<ObjectOrInterfaceDefinition>> = {}
+> {
+	readonly [ShapeDefinitionBrand]: true;
+	readonly __shapeId: string;
+	readonly __debugName: string | undefined;
+	readonly __baseType: BASE;
+	readonly __baseTypeApiName: string;
+	readonly __props: Readonly<Record<string, unknown>>;
+	readonly __derivedLinks: readonly unknown[];
+	readonly __selectedPropsType: SELECTED_PROPS;
+	readonly __derivedLinksType: DERIVED_LINKS;
+}
+export type ShapeBaseType<S extends ShapeDefinition<ObjectOrInterfaceDefinition>> = S extends ShapeDefinition<infer BASE, infer _P, infer _L> ? BASE : never;
+export type ShapeSelectedProps<S extends ShapeDefinition<ObjectOrInterfaceDefinition>> = S extends ShapeDefinition<infer _B, infer PROPS, infer _L> ? PROPS : never;
+export type ShapeDerivedLinks<S extends ShapeDefinition<ObjectOrInterfaceDefinition>> = S extends ShapeDefinition<infer _B, infer _P, infer LINKS> ? LINKS : never;
+export type ShapeInstance<S extends ShapeDefinition<ObjectOrInterfaceDefinition>> = S extends ShapeDefinition<infer BASE, infer PROPS, infer LINKS> ? OsdkBase<BASE> & {
+	readonly $rid: string
+} & PROPS & { [K in keyof LINKS] : LINKS[K] extends ShapeDefinition<ObjectOrInterfaceDefinition> ? ShapeInstance<LINKS[K]>[] : never } : never;
+export type PropertyType<
+	BASE extends ObjectOrInterfaceDefinition,
+	K extends PropertyKeys<BASE>
+> = CompileTimeMetadata<BASE>["props"][K];
+export type RequiredProperty<T> = NonNullable<T>;
+export interface ShapeLinkBuilder<
+	SOURCE extends ObjectOrInterfaceDefinition,
+	CURRENT extends ObjectOrInterfaceDefinition
+> {
+	pivotTo<L extends LinkNames<CURRENT>>(link: L): ShapeLinkBuilder<SOURCE, LinkedType<CURRENT, L>>;
+	where(clause: WhereClause<CURRENT>): ShapeLinkBuilder<SOURCE, CURRENT>;
+	union(...others: ShapeLinkBuilder<SOURCE, CURRENT>[]): ShapeLinkBuilder<SOURCE, CURRENT>;
+	intersect(...others: ShapeLinkBuilder<SOURCE, CURRENT>[]): ShapeLinkBuilder<SOURCE, CURRENT>;
+	subtract(...others: ShapeLinkBuilder<SOURCE, CURRENT>[]): ShapeLinkBuilder<SOURCE, CURRENT>;
+	orderBy<K extends PropertyKeys<CURRENT>>(property: K, direction?: "asc" | "desc"): ShapeLinkBuilder<SOURCE, CURRENT>;
+	limit(n: number): ShapeLinkBuilder<SOURCE, CURRENT>;
+	distinct(): ShapeLinkBuilder<SOURCE, CURRENT>;
+	as<TARGET_SHAPE extends ShapeDefinition<CURRENT>>(shape: TARGET_SHAPE, config?: DerivedLinkConfig): ShapeLinkResult<TARGET_SHAPE>;
+	readonly $primaryKey: symbol;
+}
+export interface ShapeLinkBuilderInternal extends ShapeLinkBuilder<ObjectOrInterfaceDefinition, ObjectOrInterfaceDefinition> {
+	toObjectSetDef(): ShapeLinkObjectSetDef;
+}
+export interface ShapeBuilder<
+	BASE extends ObjectOrInterfaceDefinition,
+	PROPS extends Record<string, unknown> = {},
+	LINKS extends Record<string, ShapeDefinition<ObjectOrInterfaceDefinition>> = {}
+> {
+	select<K extends Exclude<PropertyKeys<BASE>, keyof PROPS>>(...props: K[]): ShapeBuilder<BASE, PROPS & { [P in K] : PropertyType<BASE, P> }, LINKS>;
+	require<K extends Exclude<PropertyKeys<BASE>, keyof PROPS>>(...props: K[]): ShapeBuilder<BASE, PROPS & { [P in K] : RequiredProperty<PropertyType<BASE, P>> }, LINKS>;
+	dropIfNull<K extends Exclude<PropertyKeys<BASE>, keyof PROPS>>(...props: K[]): ShapeBuilder<BASE, PROPS & { [P in K] : RequiredProperty<PropertyType<BASE, P>> }, LINKS>;
+	withDefault<
+		K extends Exclude<PropertyKeys<BASE>, keyof PROPS>,
+		V extends NonNullable<PropertyType<BASE, K>>
+	>(prop: K, defaultValue: V): ShapeBuilder<BASE, PROPS & { [P in K] : NonNullable<PropertyType<BASE, P>> }, LINKS>;
+	withTransform<
+		K extends Exclude<PropertyKeys<BASE>, keyof PROPS>,
+		R
+	>(prop: K, transform: (value: PropertyType<BASE, K>) => R): ShapeBuilder<BASE, PROPS & { [P in K] : R }, LINKS>;
+	deriveLink<
+		NAME extends string,
+		TARGET_SHAPE extends ShapeDefinition<ObjectOrInterfaceDefinition>
+	>(name: NAME, builder: (linkBuilder: ShapeLinkBuilder<BASE, BASE>) => ShapeLinkResult<TARGET_SHAPE>): ShapeBuilder<BASE, PROPS, LINKS & { [K in NAME] : TARGET_SHAPE }>;
+	build(): ShapeDefinition<BASE, PROPS, LINKS>;
+}
+export interface LinkLoadConfig {
+	pageSize?: number;
+	autoFetchMore?: boolean | number;
+	streamUpdates?: boolean;
+	defer?: boolean;
+}
+export interface LinkStatus {
+	isLoading: boolean;
+	error: Error | undefined;
+	hasMore: boolean;
+	fetchMore: () => Promise<void>;
+}
+export interface NullabilityViolation {
+	property: string;
+	primaryKey: unknown;
+	constraint: "require" | "dropIfNull" | "transformError";
+}
+export declare class ShapeNullabilityError extends Error {
+	readonly shape: ShapeDefinition<ObjectOrInterfaceDefinition>;
+	readonly violations: readonly NullabilityViolation[];
+	constructor(shape: ShapeDefinition<ObjectOrInterfaceDefinition>, violations: readonly NullabilityViolation[]);
+}
+export {};

package/build/types/shapes/ShapeDefinition.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"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","names":["SourcePrimaryKeySymbol: unique symbol","value: unknown","ShapeDefinitionBrand: unique symbol","ShapeLinkResultBrand: unique symbol","link: L","clause: WhereClause<CURRENT>","property: K","direction?: \"asc\" | \"desc\"","n: number","shape: TARGET_SHAPE","config?: DerivedLinkConfig","prop: K","defaultValue: V","transform: (value: PropertyType<BASE, K>) => R","value: PropertyType<BASE, K>","name: NAME","builder: (\n      linkBuilder: ShapeLinkBuilder<BASE, BASE>,\n    ) => ShapeLinkResult<TARGET_SHAPE>","linkBuilder: ShapeLinkBuilder<BASE, BASE>","shape: ShapeDefinition<ObjectOrInterfaceDefinition>","violations: readonly NullabilityViolation[]"],"sources":["../../../src/shapes/ShapeDefinition.ts"],"version":3,"file":"ShapeDefinition.d.ts"}

package/build/types/shapes/computeShapeId.d.ts

@@ -0,0 +1,14 @@
+import type { ShapeDerivedLinkDef, ShapePropertyConfig } from "./ShapeDefinition.js";
+interface ShapeIdInput {
+	baseTypeApiName: string;
+	props: Record<string, ShapePropertyConfig>;
+	derivedLinks: readonly ShapeDerivedLinkDef[];
+}
+/**
+* Computes a stable, deterministic identifier for a shape definition.
+* The ID uniquely represents the combination of base type, property
+* selections/nullability configs, and derived link definitions so
+* that identical shapes produce the same ID across calls.
+*/
+export declare function computeShapeId(input: ShapeIdInput): string;
+export {};

package/build/types/shapes/computeShapeId.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAgBA,cACE,qBAEA,2BACK,sBAAuB;UAEpB,aAAa;CACrB;CACA,OAAO,eAAe;CACtB,uBAAuB;AACxB;;;;;;;AAoBD,OAAO,iBAAS,eAAeA,OAAO","names":["input: ShapeIdInput"],"sources":["../../../src/shapes/computeShapeId.ts"],"version":3,"file":"computeShapeId.d.ts"}

package/build/types/shapes/configToShapeDefinition.d.ts

@@ -0,0 +1,6 @@
+import type { ObjectOrInterfaceDefinition } from "../ontology/ObjectOrInterface.js";
+import type { InferShapeDefinition, InlineShapeConfig } from "./InlineShapeConfig.js";
+export declare function configToShapeDefinition<
+	BASE extends ObjectOrInterfaceDefinition,
+	const C extends InlineShapeConfig<BASE>
+>(baseType: BASE, config: C): InferShapeDefinition<BASE, C>;

package/build/types/shapes/configToShapeDefinition.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAgBA,cAAc,mCAAmC,kCAAmC;AAEpF,cACE,sBACA,yBACK,wBAAyB;AAWhC,OAAO,iBAAS;CACd,aAAa;OACP,UAAU,kBAAkB;EAElCA,UAAU,MACVC,QAAQ,IACP,qBAAqB,MAAM","names":["baseType: BASE","config: C"],"sources":["../../../src/shapes/configToShapeDefinition.ts"],"version":3,"file":"configToShapeDefinition.d.ts"}

package/build/types/shapes/index.d.ts

@@ -0,0 +1,5 @@
+export type { LinkLoadConfig, LinkStatus, NullabilityViolation, PropertyType, RequiredProperty, ShapeBaseType, ShapeBuilder, ShapeDefinition, ShapeDerivedLinks, ShapeInstance, ShapeLinkBuilder, ShapeLinkResult } from "./ShapeDefinition.js";
+export type { InferShapeDefinition, InlineLinkConfig, InlineShapeConfig } from "./InlineShapeConfig.js";
+export { isSourcePkSymbol, ShapeNullabilityError, SourcePrimaryKeySymbol } from "./ShapeDefinition.js";
+export { createShapeBuilder } from "./ShapeBuilder.js";
+export { configToShapeDefinition } from "./configToShapeDefinition.js";

package/build/types/shapes/index.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAiBA,cACE,gBACA,YACA,sBACA,cACA,kBACA,eACA,cACA,iBACA,mBACA,eACA,kBACA,uBACK;AAGP,cACE,sBACA,kBACA,yBACK;AAGP,SACE,kBACA,uBACA,8BACK;AAGP,SAAS,0BAA0B;AAGnC,SAAS,+BAA+B","names":[],"sources":["../../../src/shapes/index.ts"],"version":3,"file":"index.d.ts"}

package/build/types/shapes/internal.d.ts

@@ -0,0 +1 @@
+export type { DerivedLinkConfig, NullabilityOp, ShapeDerivedLinkDef, ShapeLinkObjectSetDef, ShapeLinkOrderBy, ShapeLinkSegment, ShapeLinkSetOperation, ShapePropertyConfig } from "./ShapeDefinition.js";

package/build/types/shapes/internal.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAgBA,cACE,mBACA,eACA,qBACA,uBACA,kBACA,kBACA,uBACA,2BACK","names":[],"sources":["../../../src/shapes/internal.ts"],"version":3,"file":"internal.d.ts"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdk/api",
-  "version": "2.8.0-beta.27",
+  "version": "2.8.0-beta.29",
   "description": "",
   "access": "public",
   "license": "Apache-2.0",
@@ -18,6 +18,15 @@
       "require": "./build/cjs/index.cjs",
       "default": "./build/browser/index.js"
     },
+    "./shapes-internal": {
+      "browser": "./build/browser/public/shapes-internal.js",
+      "import": {
+        "types": "./build/types/public/shapes-internal.d.ts",
+        "default": "./build/esm/public/shapes-internal.js"
+      },
+      "require": "./build/cjs/public/shapes-internal.cjs",
+      "default": "./build/browser/public/shapes-internal.js"
+    },
     "./unstable": {
       "browser": "./build/browser/public/unstable.js",
       "import": {

package/shapes-internal.d.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from "./build/cjs/public/shapes-internal.cjs";