@pylo/node 0.0.11 → 0.1.0

package/dist/cli.js

@@ -34,7 +34,6 @@ async function loadConfig(cwd) {
       }
       return {
         endpoint: DEFAULT_ENDPOINT,
-        unknownFieldBehavior: "error",
         ...config
       };
     }
@@ -124,18 +123,15 @@ query PyloSchemaFetch($pagination: PaginationInput) {
   }
 }
 `;
-async function fetchSchema(config) {
+async function fetchSchemaWith(request) {
   var _a, _b;
   const allEntities = [];
   let page = 1;
   let hasMore = true;
   while (hasMore) {
-    const response = await graphqlRequestWithApiKey(
-      config.endpoint,
-      ENTITY_LIST_QUERY,
-      { pagination: { page, per_page: 50 } },
-      config.apiKey
-    );
+    const response = await request(ENTITY_LIST_QUERY, {
+      pagination: { page, per_page: 50 }
+    });
     if (response.errors) {
       const errMsg = Array.isArray(response.errors) ? response.errors.map((e) => e.message).join(", ") : (_b = (_a = response.errors.generalError) == null ? void 0 : _a.message) != null ? _b : "Unknown error";
       throw new Error(`Failed to fetch schema: ${errMsg}`);
@@ -150,6 +146,11 @@ async function fetchSchema(config) {
   }
   return allEntities;
 }
+async function fetchSchema(config) {
+  return fetchSchemaWith(
+    (query, variables) => graphqlRequestWithApiKey(config.endpoint, query, variables, config.apiKey)
+  );
+}
 var DATA_TYPE_MAP = {
   TEXT: "string",
   LONGTEXT: "string",
@@ -263,6 +264,7 @@ function analyzeEntities(rawEntities) {
   });
 }
 var VARIANT_TYPE = "{ variant: string; value: string }";
+var REGISTERABLE_SOURCES = /* @__PURE__ */ new Set(["@pylo/node", "@pylo/nextjs"]);
 function fieldTypeString(field) {
   if (field.nullable) {
     return `${field.tsType} | null`;
@@ -276,10 +278,21 @@ function indent(text, level) {
 function getVariantFieldNames(entity) {
   return entity.fields.filter((f) => f.variantFieldName !== null).map((f) => f.variantFieldName);
 }
+var NON_WRITABLE_FIELDS = /* @__PURE__ */ new Set(["integer_id", "created_at", "updated_at"]);
+function generateReplaceVariablesField(entity) {
+  const fieldNames = entity.fields.map((f) => f.name).filter((name) => !NON_WRITABLE_FIELDS.has(name));
+  if (fieldNames.length === 0) return null;
+  const union = fieldNames.map((name) => `'${name}'`).join(" | ");
+  return [
+    "/**",
+    " * Field names whose template variables (e.g. `${replace_uuid.myNewEntity}`) the server",
+    " * should resolve to their concrete values during this upsert.",
+    " */",
+    `replace_variables?: Array<${union}>;`
+  ].join("\n");
+}
 function generateEntityFieldsType(entity) {
-  const lines = entity.fields.map(
-    (f) => `${f.name}: ${fieldTypeString(f)};`
-  );
+  const lines = entity.fields.map((f) => `${f.name}: ${fieldTypeString(f)};`);
   for (const variantName of getVariantFieldNames(entity)) {
     lines.push(`${variantName}: ${VARIANT_TYPE}[] | null;`);
   }
@@ -305,9 +318,7 @@ function generateCreateInputType(entity) {
   for (const rel of entity.relations) {
     for (const suffix of rel.suffixes) {
       const valueType = rel.type === "hasMany" ? "Record<string, unknown>[]" : "Record<string, unknown>";
-      lines.push(
-        `${rel.fieldName}${suffix}?: ${valueType};`
-      );
+      lines.push(`${rel.fieldName}${suffix}?: ${valueType};`);
     }
   }
   return lines.join("\n");
@@ -318,6 +329,10 @@ function generateUpdateInputType(entity) {
   lines.push(
     "__search_value?: { field: string; value?: string; not_found_behavior?: 'create' | 'ignore' | 'error'; search_in_all_field_variants?: boolean; multiple_results_allowed?: boolean; multiple_results_use_latest?: boolean };"
   );
+  const replaceVariables = generateReplaceVariablesField(entity);
+  if (replaceVariables) {
+    lines.push(replaceVariables);
+  }
   for (const field of entity.fields) {
     if (field.name === "id" || field.name === "integer_id") continue;
     if (field.name === "created_at" || field.name === "updated_at") continue;
@@ -329,9 +344,7 @@ function generateUpdateInputType(entity) {
   for (const rel of entity.relations) {
     for (const suffix of rel.suffixes) {
       const valueType = rel.type === "hasMany" ? "Record<string, unknown>[]" : "Record<string, unknown>";
-      lines.push(
-        `${rel.fieldName}${suffix}?: ${valueType};`
-      );
+      lines.push(`${rel.fieldName}${suffix}?: ${valueType};`);
     }
   }
   return lines.join("\n");
@@ -362,8 +375,6 @@ function generateIndexFile(entities, importSource) {
     "  SortInput,",
     "  SortOrder,",
     "  SearchValueInput,",
-    "  SchemaMetadata,",
-    "  EntityMetadata,",
     `} from '${importSource}';`,
     ""
   );
@@ -400,6 +411,16 @@ function generateIndexFile(entities, importSource) {
     lines.push("  };");
   }
   lines.push("}", "");
+  if (REGISTERABLE_SOURCES.has(importSource)) {
+    lines.push(
+      `declare module '${importSource}' {`,
+      "  interface PyloRegister {",
+      "    schema: PyloSchema;",
+      "  }",
+      "}",
+      ""
+    );
+  }
   return lines.join("\n");
 }
 function generateEntitiesFile(entities, importSource) {
@@ -425,57 +446,19 @@ function generateEntitiesFile(entities, importSource) {
     }
     for (const rel of entity.relations) {
       if (rel.type === "hasOne") {
-        lines.push(`  ${rel.fieldName}?: { data: ${rel.targetEntityPascalName} } | null;`);
+        lines.push(
+          `  ${rel.fieldName}?: { data: ${rel.targetEntityPascalName} } | null;`
+        );
       } else {
-        lines.push(`  ${rel.fieldName}?: { data: ${rel.targetEntityPascalName}[]; pagination: PaginationData };`);
+        lines.push(
+          `  ${rel.fieldName}?: { data: ${rel.targetEntityPascalName}[]; pagination: PaginationData };`
+        );
       }
     }
     lines.push("}", "");
   }
   return lines.join("\n");
 }
-function generateSchemaMetadataFile(entities, unknownFieldBehavior, importSource) {
-  const lines = [];
-  lines.push(
-    "// Auto-generated by @pylo/core codegen \u2014 DO NOT EDIT",
-    "",
-    `import type { SchemaMetadata } from '${importSource}';`,
-    "",
-    "export const schemaMetadata: SchemaMetadata = {",
-    `  unknownFieldBehavior: '${unknownFieldBehavior}',`,
-    "  entities: {"
-  );
-  for (const entity of entities) {
-    lines.push(`    ${entity.key}: {`);
-    lines.push(`      pascalName: '${entity.pascalName}',`);
-    const scalarNames = entity.fields.map((f) => `'${f.name}'`).join(", ");
-    lines.push(`      scalarFieldNames: [${scalarNames}],`);
-    const variantNames = getVariantFieldNames(entity);
-    if (variantNames.length > 0) {
-      const variantNamesStr = variantNames.map((n) => `'${n}'`).join(", ");
-      lines.push(`      variantFieldNames: [${variantNamesStr}],`);
-    }
-    const enumFields = entity.fields.filter((f) => f.enum !== null);
-    if (enumFields.length > 0) {
-      lines.push("      enumFields: {");
-      for (const f of enumFields) {
-        const vals = f.enum.values.map((v) => `'${v}'`).join(", ");
-        lines.push(`        ${f.name}: [${vals}],`);
-      }
-      lines.push("      },");
-    }
-    lines.push("      relations: {");
-    for (const rel of entity.relations) {
-      lines.push(
-        `        ${rel.fieldName}: { type: '${rel.type}', entity: '${rel.targetEntityKey}', pascalName: '${rel.targetEntityPascalName}' },`
-      );
-    }
-    lines.push("      },");
-    lines.push("    },");
-  }
-  lines.push("  },", "};", "");
-  return lines.join("\n");
-}
 function writeGeneratedFiles(outputDir, files) {
   mkdirSync(outputDir, { recursive: true });
   for (const [filename, content] of Object.entries(files)) {
@@ -499,8 +482,7 @@ async function generate(options) {
   console.log("Generating types...");
   const files = {
     "index.ts": generateIndexFile(entities, importSource),
-    "entities.ts": generateEntitiesFile(entities, importSource),
-    "schema-metadata.ts": generateSchemaMetadataFile(entities, config.unknownFieldBehavior, importSource)
+    "entities.ts": generateEntitiesFile(entities, importSource)
   };
   console.log(`Writing files to ${outputDir}...`);
   writeGeneratedFiles(outputDir, files);

package/dist/codegen.d.ts

@@ -1 +1,2 @@
 export { PyloConfig, defineConfig } from '@pylo/core/codegen';
+import '@pylo/core/schema';

package/dist/index.d.ts

@@ -47,21 +47,56 @@ interface PyloEvent {
     ts: string;
     properties: Record<string, unknown>;
 }
-interface EntityMetadata {
-    pascalName: string;
-    scalarFieldNames: string[];
-    variantFieldNames?: string[];
-    jsonFieldNames?: string[];
-    enumFields?: Record<string, string[]>;
-    relations: Record<string, {
-        type: "hasOne" | "hasMany";
-        entity: string;
-        pascalName: string;
-    }>;
+type AggregateFunction = "count" | "sum" | "avg" | "min" | "max";
+interface AggregateInput {
+    field: string;
+    function: AggregateFunction;
+    alias?: string;
+}
+interface TimeBucketInput {
+    field?: string;
+    interval: string;
+    timezone?: string;
+}
+interface DimensionInput {
+    field?: string;
+    timeBucket?: TimeBucketInput;
+}
+interface EventListFilterInput {
+    query?: QueryInput[];
+    sortby?: SortInput[];
+    aggregate?: AggregateInput[];
+    dimensions?: DimensionInput[];
+    limit?: number;
 }
-interface SchemaMetadata {
-    entities: Record<string, EntityMetadata>;
-    unknownFieldBehavior?: "error" | "ignore";
+interface EventListOptions {
+    filter?: EventListFilterInput;
+    pagination?: PaginationInput;
+    select_fields?: string[];
+    interval?: string;
+    timezone?: string;
+    group_by?: string[];
+    startTime?: string;
+}
+interface PyloEventListResult {
+    data: Array<Record<string, unknown>>;
+    pagination: PaginationData;
+    aggregations: Record<string, unknown> | null;
+}
+interface PyloEventProperty {
+    path: string;
+    type: string;
+}
+interface PyloEventFieldValue {
+    value: string;
+    count: number;
+}
+interface PyloEventPropertyKeysOptions {
+    filter?: FilterInput;
+}
+interface PyloEventFieldValuesOptions {
+    startTime?: string;
+    limit?: number;
 }
 
 type EntityName<S> = string & keyof S;
@@ -77,26 +112,26 @@ type UpsertInput<S, E extends EntityName<S>> = S[E] extends {
 type OmitNever<T> = {
     [K in keyof T as T[K] extends never ? never : K]: T[K];
 };
-type EntitySelect<S, E extends EntityName<S>, Depth extends number = 0> = Depth extends 5 ? Record<string, true> : OmitNever<{
+type EntitySelect<S, E extends EntityName<S>, Depth extends number = 0> = Depth extends 5 ? Record<string, never> : OmitNever<{
     [K in keyof EntityFields<S, E>]?: true;
 }> & {
     [K in keyof EntityRelations<S, E>]?: EntityRelations<S, E>[K] extends {
         type: "hasOne";
         entity: infer Target;
-    } ? Target extends EntityName<S> ? true | {
-        select?: EntitySelect<S, Target, Increment[Depth]>;
+    } ? Target extends EntityName<S> ? {
+        select: EntitySelect<S, Target, Increment[Depth]>;
         filter?: FilterInput;
-    } : true : EntityRelations<S, E>[K] extends {
+    } : never : EntityRelations<S, E>[K] extends {
         type: "hasMany";
         entity: infer Target;
-    } ? Target extends EntityName<S> ? true | {
-        select?: EntitySelect<S, Target, Increment[Depth]>;
+    } ? Target extends EntityName<S> ? {
+        select: EntitySelect<S, Target, Increment[Depth]>;
         filter?: FilterInput;
         pagination?: PaginationInput;
-    } : true : true;
+    } : never : never;
 };
 type Increment = [1, 2, 3, 4, 5, 5];
-type EntityResult<S, E extends EntityName<S>, Select extends EntitySelect<S, E> | undefined = undefined, Depth extends number = 0> = Depth extends 5 ? Record<string, unknown> : Select extends undefined ? EntityFields<S, E> : Select extends EntitySelect<S, E> ? OmitNever<ScalarResult<S, E, Select> & RelationResult<S, E, Select, Depth>> : EntityFields<S, E>;
+type EntityResult<S, E extends EntityName<S>, Select extends EntitySelect<S, E>, Depth extends number = 0> = Depth extends 5 ? Record<string, unknown> : Select extends EntitySelect<S, E> ? OmitNever<ScalarResult<S, E, Select> & RelationResult<S, E, Select, Depth>> : EntityFields<S, E>;
 type ScalarResult<S, E extends EntityName<S>, Select extends EntitySelect<S, E>> = {
     [K in keyof Select & keyof EntityFields<S, E>]: Select[K] extends true ? EntityFields<S, E>[K] : never;
 };
@@ -108,36 +143,29 @@ type RelationResult<S, E extends EntityName<S>, Select extends EntitySelect<S, E
         select: infer SubSelect;
     } ? SubSelect extends EntitySelect<S, Target> ? {
         data: EntityResult<S, Target, SubSelect, Increment[Depth]>;
-    } | null : {
-        data: EntityFields<S, Target>;
-    } | null : Select[K] extends true ? {
-        data: EntityFields<S, Target>;
-    } | null : never : never : EntityRelations<S, E>[K] extends {
+    } | null : never : never : never : EntityRelations<S, E>[K] extends {
         type: "hasMany";
         entity: infer Target;
     } ? Target extends EntityName<S> ? Select[K] extends {
         select: infer SubSelect;
     } ? SubSelect extends EntitySelect<S, Target> ? {
         data: Array<EntityResult<S, Target, SubSelect, Increment[Depth]>>;
+    } & (Select[K] extends {
+        pagination: unknown;
+    } ? {
         pagination: PaginationData;
-    } : {
-        data: Array<EntityFields<S, Target>>;
-        pagination: PaginationData;
-    } : Select[K] extends true ? {
-        data: Array<EntityFields<S, Target>>;
-        pagination: PaginationData;
-    } : never : never : never;
+    } : unknown) : never : never : never : never;
 };
 type StrictSelect<Sel, Valid> = Valid & {
     [K in keyof Sel]: K extends keyof Valid ? Sel[K] : never;
 };
-type ListOptions<S, E extends EntityName<S>, Sel extends EntitySelect<S, E> | undefined = undefined> = {
-    select?: Sel extends undefined ? EntitySelect<S, E> : StrictSelect<Sel, EntitySelect<S, E>>;
+type ListOptions<S, E extends EntityName<S>, Sel extends EntitySelect<S, E>> = {
+    select: StrictSelect<Sel, EntitySelect<S, E>>;
     filter?: FilterInput;
     pagination?: PaginationInput;
 };
-type ByIdOptions<S, E extends EntityName<S>, Sel extends EntitySelect<S, E> | undefined = undefined> = {
-    select?: Sel extends undefined ? EntitySelect<S, E> : StrictSelect<Sel, EntitySelect<S, E>>;
+type ByIdOptions<S, E extends EntityName<S>, Sel extends EntitySelect<S, E>> = {
+    select: StrictSelect<Sel, EntitySelect<S, E>>;
 };
 interface ListResult<T> {
     data: T[];
@@ -160,13 +188,12 @@ type AuthProvider = () => Promise<{
 }>;
 interface ClientOptions {
     endpoint?: string;
-    schemaMetadata: SchemaMetadata;
     auth: AuthProvider;
     headers?: Record<string, string>;
 }
 interface EntityClient<S, E extends EntityName<S>> {
-    list<Sel extends EntitySelect<S, E> | undefined = undefined>(options?: ListOptions<S, E, Sel> & RequestOptions): Promise<ListResult<EntityResult<S, E, Sel>>>;
-    byId<Sel extends EntitySelect<S, E> | undefined = undefined>(id: string, options?: ByIdOptions<S, E, Sel> & RequestOptions): Promise<EntityResult<S, E, Sel> | null>;
+    list<Sel extends EntitySelect<S, E>>(options: ListOptions<S, E, Sel> & RequestOptions): Promise<ListResult<EntityResult<S, E, Sel>>>;
+    byId<Sel extends EntitySelect<S, E>>(id: string, options: ByIdOptions<S, E, Sel> & RequestOptions): Promise<EntityResult<S, E, Sel> | null>;
     upsert(input: UpsertInput<S, E>, options?: MutationRequestOptions): Promise<{
         id: string;
     }>;
@@ -175,18 +202,76 @@ interface EntityClient<S, E extends EntityName<S>> {
     }>;
 }
 type IngestEvents = (events: PyloEventInput[], options?: MutationRequestOptions) => Promise<PyloEvent[]>;
+interface EventsClient {
+    list(options?: EventListOptions & RequestOptions): Promise<PyloEventListResult>;
+    propertyKeys(options?: PyloEventPropertyKeysOptions & RequestOptions): Promise<PyloEventProperty[]>;
+    fieldValues(field: string, options?: PyloEventFieldValuesOptions & RequestOptions): Promise<PyloEventFieldValue[]>;
+}
 type PyloClient<S> = {
     [E in EntityName<S>]: EntityClient<S, E>;
 } & {
     ingestEvents: IngestEvents;
+    events: EventsClient;
 };
 
 interface NodeClientOptions {
     apiKey: string;
     endpoint?: string;
-    schemaMetadata: SchemaMetadata;
     headers?: Record<string, string>;
 }
 declare function createPyloNode<S>(options: NodeClientOptions): PyloClient<S>;
+/**
+ * Augmentable registry that lets a host pin the schema type for the injected
+ * `pylo` client. Generated code augments it, e.g.:
+ *
+ *   declare module "@pylo/node" {
+ *     interface PyloRegister { schema: PyloSchema }
+ *   }
+ *
+ * With no augmentation the client falls back to an untyped (`any`) schema.
+ */
+interface PyloRegister {
+}
+type RegisteredSchema = PyloRegister extends {
+    schema: infer S;
+} ? S : any;
+/**
+ * Entity keys available on the registered schema — e.g. `"contact"`. Use as the
+ * type parameter for {@link PyloSelect} / {@link PyloResult}.
+ */
+type PyloEntity = EntityName<RegisteredSchema>;
+/**
+ * A reusable, type-safe selection for one entity on the registered schema.
+ * Lets you define what to fetch once and reuse it across calls.
+ *
+ * Declare the selection with `satisfies` (not a plain `: PyloSelect<…>`
+ * annotation) so the exact set of selected fields is preserved — that's what
+ * keeps {@link PyloResult} precise:
+ *
+ * ```ts
+ * const contactSelect = {
+ *   name: true,
+ *   email: true,
+ *   company: { select: { name: true } },
+ * } satisfies PyloSelect<"contact">;
+ *
+ * const { data } = await pylo.contact.list({ select: contactSelect });
+ * type Contact = PyloResult<"contact", typeof contactSelect>;
+ * ```
+ */
+type PyloSelect<E extends PyloEntity> = EntitySelect<RegisteredSchema, E>;
+/**
+ * The row type returned for a given entity and selection. Pair with
+ * `typeof <yourSelect>` (see {@link PyloSelect}) for an exact result type.
+ */
+type PyloResult<E extends PyloEntity, Sel extends PyloSelect<E>> = EntityResult<RegisteredSchema, E, Sel>;
+/**
+ * Zero-config client for environments that inject a ready-made client onto
+ * `globalThis.__PYLO_FLOW_CLIENT__` — e.g. the Pylo flow worker, which builds
+ * the client from the flow's API key and the customer's schema before running
+ * an action. Property access is forwarded to the current global client at
+ * access time, so a worker reused across customers always sees the live one.
+ */
+declare const pylo: PyloClient<RegisteredSchema>;
 
-export { type AuthProvider, type ByIdOptions, type ClientOptions, type EntityClient, type EntityFields, type EntityMetadata, type EntityName, type EntityRelations, type EntityResult, type EntitySelect, type FilterInput, type IngestEvents, type ListOptions, type ListResult, type MutationRequestOptions, type PaginationData, type PaginationInput, type PyloClient, PyloError, type PyloEvent, type PyloEventInput, type QueryInput, type QueryInputCondition, type QueryOperator, type RequestOptions, type SchemaMetadata, type SearchValueInput, type SortInput, type SortOrder, type StrictSelect, type UpsertInput, createPyloNode };
+export { type AggregateFunction, type AggregateInput, type AuthProvider, type ByIdOptions, type ClientOptions, type DimensionInput, type EntityClient, type EntityFields, type EntityName, type EntityRelations, type EntityResult, type EntitySelect, type EventListFilterInput, type EventListOptions, type EventsClient, type FilterInput, type IngestEvents, type ListOptions, type ListResult, type MutationRequestOptions, type PaginationData, type PaginationInput, type PyloClient, type PyloEntity, PyloError, type PyloEvent, type PyloEventFieldValue, type PyloEventFieldValuesOptions, type PyloEventInput, type PyloEventListResult, type PyloEventProperty, type PyloEventPropertyKeysOptions, type PyloRegister, type PyloResult, type PyloSelect, type QueryInput, type QueryInputCondition, type QueryOperator, type RegisteredSchema, type RequestOptions, type SearchValueInput, type SortInput, type SortOrder, type StrictSelect, type TimeBucketInput, type UpsertInput, createPyloNode, pylo };