brickr-sdk 0.1.0

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "brickr-sdk",
+  "version": "0.1.0",
+  "description": "Brickr SDK for defining code function nodes",
+  "type": "module",
+  "main": "./src/index.js",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "types": "./src/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/index.d.ts

@@ -0,0 +1,121 @@
+export type PrimitivePinType = 'string' | 'number' | 'boolean' | 'any' | 'sequence';
+
+export interface BrickrPin {
+  id: string;
+  label: string;
+  type: string;
+  optional?: boolean;
+  description?: string;
+  defaultValue?: unknown;
+  portOnly?: boolean;
+  pinOnly?: boolean;
+  allowPortOnlyFalse?: boolean;
+  allowPinOnlyFalse?: boolean;
+}
+
+export interface PinBuilder {
+  optional(): PinBuilder;
+  description(text: string): PinBuilder;
+  default(value: unknown): PinBuilder;
+  portOnly(enabled?: boolean): PinBuilder;
+  pinOnly(enabled?: boolean): PinBuilder;
+  allowInlineValue(enabled?: boolean): PinBuilder;
+}
+
+export interface CodeFunctionRunContext<TInputs = Record<string, unknown>> {
+  inputs: TInputs;
+  request?: {
+    method?: string;
+    url?: string;
+    headers?: Record<string, string>;
+  };
+  env?: Record<string, unknown>;
+  secret(name: string): string;
+  log(...args: unknown[]): void;
+  fail(message: string, code?: string): never;
+}
+
+export interface CodeFunctionNodeDefinition {
+  __brickrType: 'code-function-node';
+  nodeKey: string;
+  name: string;
+  description?: string;
+  category?: string;
+  inputs: BrickrPin[];
+  outputs: BrickrPin[];
+  run: (ctx: CodeFunctionRunContext) => Promise<Record<string, unknown>> | Record<string, unknown>;
+}
+
+export interface EnumDefinition {
+  __brickrType: 'enum';
+  name: string;
+  description?: string;
+  values: Array<{ key: string; value: string; label?: string }>;
+}
+
+export interface StructureDefinition {
+  __brickrType: 'structure';
+  name: string;
+  description?: string;
+  fields: Array<{ name: string; type: string; label?: string; required?: boolean }>;
+}
+
+export interface SecretDefinition {
+  __brickrType: 'secret';
+  name: string;
+  description?: string;
+  required?: boolean;
+}
+
+export declare const t: {
+  string(): PinBuilder;
+  number(): PinBuilder;
+  boolean(): PinBuilder;
+  any(): PinBuilder;
+  object(name?: string): PinBuilder;
+  enumValue(name?: string): PinBuilder;
+  struct(name: string): PinBuilder;
+  array(inner: PinBuilder): PinBuilder;
+};
+
+export declare const seq: {
+  in(): PinBuilder;
+  out(): PinBuilder;
+};
+
+export declare function defineCodeFunctionNode(config: {
+  nodeKey: string;
+  id?: string;
+  name: string;
+  description?: string;
+  category?: string;
+  inputs?: Record<string, PinBuilder | Partial<BrickrPin>>;
+  outputs?: Record<string, PinBuilder | Partial<BrickrPin>>;
+  run: CodeFunctionNodeDefinition['run'];
+}): CodeFunctionNodeDefinition;
+
+export declare function defineEnum(config: {
+  name: string;
+  description?: string;
+  values: Array<string | { key?: string; value?: string; label?: string }>;
+}): EnumDefinition;
+
+export declare function defineStructure(config: {
+  name: string;
+  description?: string;
+  fields: Array<{ name: string; type: string; label?: string; required?: boolean }>;
+}): StructureDefinition;
+
+export declare function defineSecret(config: {
+  name: string;
+  description?: string;
+  required?: boolean;
+}): SecretDefinition;
+
+export declare function buildManifestFromNode(nodeDefinition: CodeFunctionNodeDefinition): Omit<CodeFunctionNodeDefinition, 'run' | '__brickrType'>;
+
+export declare function collectAssets(assets: Array<EnumDefinition | StructureDefinition | SecretDefinition>): {
+  enums: EnumDefinition[];
+  structures: StructureDefinition[];
+  secrets: SecretDefinition[];
+};

package/src/index.js

@@ -0,0 +1,243 @@
+const normalizeString = (value, fallback = '') => {
+  if (typeof value === 'string') return value.trim();
+  if (value === null || typeof value === 'undefined') return fallback;
+  return String(value).trim();
+};
+
+const ensureLabel = (value, fallback = '') => {
+  const normalized = normalizeString(value, fallback);
+  return normalized || fallback;
+};
+
+class PinBuilder {
+  constructor(type, options = {}) {
+    this._type = type;
+    this._optional = !!options.optional;
+    this._description = options.description || '';
+    this._defaultValue = options.defaultValue;
+    this._hasDefault = Object.prototype.hasOwnProperty.call(options, 'defaultValue');
+    const hasPortOnly = Object.prototype.hasOwnProperty.call(options, 'portOnly');
+    const hasPinOnly = Object.prototype.hasOwnProperty.call(options, 'pinOnly');
+    this._portOnly = hasPortOnly ? !!options.portOnly : (hasPinOnly ? !!options.pinOnly : false);
+    this._allowPortOnlyFalse = Object.prototype.hasOwnProperty.call(options, 'allowPortOnlyFalse')
+      ? options.allowPortOnlyFalse
+      : options.allowPinOnlyFalse;
+  }
+
+  optional() {
+    this._optional = true;
+    return this;
+  }
+
+  description(text) {
+    this._description = normalizeString(text);
+    return this;
+  }
+
+  default(value) {
+    this._defaultValue = value;
+    this._hasDefault = true;
+    return this;
+  }
+
+  portOnly(enabled = true) {
+    this._portOnly = !!enabled;
+    if (enabled === false) {
+      this._allowPortOnlyFalse = true;
+    }
+    return this;
+  }
+
+  // Alias: many users think in "pinOnly" terms.
+  pinOnly(enabled = true) {
+    return this.portOnly(enabled);
+  }
+
+  allowInlineValue(enabled = true) {
+    if (enabled) {
+      this._portOnly = false;
+      this._allowPortOnlyFalse = true;
+    } else {
+      this._portOnly = true;
+    }
+    return this;
+  }
+
+  toPin(id, label) {
+    const pin = {
+      id,
+      label: ensureLabel(label, id),
+      type: this._type,
+      optional: this._optional,
+      description: this._description || undefined,
+      portOnly: !!this._portOnly
+    };
+
+    if (this._allowPortOnlyFalse === false || this._allowPortOnlyFalse === true) {
+      pin.allowPortOnlyFalse = this._allowPortOnlyFalse;
+    }
+
+    if (this._hasDefault) {
+      pin.defaultValue = this._defaultValue;
+    }
+
+    return pin;
+  }
+}
+
+const createPinBuilder = (type) => new PinBuilder(type);
+
+const normalizePinEntries = (pins = {}) => {
+  if (!pins || typeof pins !== 'object') return [];
+  return Object.entries(pins).map(([id, builder]) => {
+    if (builder instanceof PinBuilder) {
+      return builder.toPin(id, id);
+    }
+
+    const fallbackType = normalizeString(builder?.type, 'any') || 'any';
+    const hasPortOnly = Object.prototype.hasOwnProperty.call(builder || {}, 'portOnly');
+    const hasPinOnly = Object.prototype.hasOwnProperty.call(builder || {}, 'pinOnly');
+    const normalizedBuilder = new PinBuilder(fallbackType, {
+      optional: !!builder?.optional,
+      description: builder?.description || '',
+      defaultValue: builder?.defaultValue,
+      portOnly: hasPortOnly ? !!builder?.portOnly : (hasPinOnly ? !!builder?.pinOnly : false),
+      allowPortOnlyFalse: Object.prototype.hasOwnProperty.call(builder || {}, 'allowPortOnlyFalse')
+        ? builder?.allowPortOnlyFalse
+        : builder?.allowPinOnlyFalse
+    });
+    return normalizedBuilder.toPin(id, builder?.label || id);
+  });
+};
+
+const buildNodeDefinition = (config = {}) => {
+  const nodeKey = normalizeString(config.nodeKey || config.id).toLowerCase();
+  const name = normalizeString(config.name, nodeKey || 'Code Function');
+  if (!nodeKey) {
+    throw new Error('defineCodeFunctionNode: "nodeKey" is required');
+  }
+  if (!config.run || typeof config.run !== 'function') {
+    throw new Error('defineCodeFunctionNode: "run" function is required');
+  }
+
+  return {
+    __brickrType: 'code-function-node',
+    nodeKey,
+    name,
+    description: normalizeString(config.description),
+    category: normalizeString(config.category, 'code-function') || 'code-function',
+    inputs: normalizePinEntries(config.inputs),
+    outputs: normalizePinEntries(config.outputs),
+    run: config.run
+  };
+};
+
+const sanitizeAssetName = (name) => normalizeString(name);
+
+export const defineCodeFunctionNode = (config) => buildNodeDefinition(config);
+
+export const defineEnum = (config = {}) => {
+  const name = sanitizeAssetName(config.name);
+  if (!name) throw new Error('defineEnum: "name" is required');
+  const values = Array.isArray(config.values) ? config.values : [];
+  return {
+    __brickrType: 'enum',
+    name,
+    description: normalizeString(config.description),
+    values: values.map((value) => {
+      if (value && typeof value === 'object') {
+        const key = normalizeString(value.key || value.value || value.label);
+        const normalizedValue = normalizeString(value.value || value.key || key);
+        const label = normalizeString(value.label || normalizedValue || key);
+        return { key, value: normalizedValue, label };
+      }
+      const normalized = normalizeString(value);
+      return { key: normalized, value: normalized, label: normalized };
+    }).filter((entry) => entry.key)
+  };
+};
+
+export const defineStructure = (config = {}) => {
+  const name = sanitizeAssetName(config.name);
+  if (!name) throw new Error('defineStructure: "name" is required');
+  const fields = Array.isArray(config.fields) ? config.fields : [];
+  return {
+    __brickrType: 'structure',
+    name,
+    description: normalizeString(config.description),
+    fields: fields.map((field) => ({
+      name: sanitizeAssetName(field?.name),
+      type: normalizeString(field?.type, 'any') || 'any',
+      label: normalizeString(field?.label || field?.name),
+      required: !!field?.required
+    })).filter((field) => field.name)
+  };
+};
+
+export const defineSecret = (config = {}) => {
+  const name = sanitizeAssetName(config.name);
+  if (!name) throw new Error('defineSecret: "name" is required');
+  return {
+    __brickrType: 'secret',
+    name,
+    description: normalizeString(config.description),
+    required: config.required !== false
+  };
+};
+
+export const seq = {
+  in: () => createPinBuilder('sequence').portOnly(true),
+  out: () => createPinBuilder('sequence').portOnly(true)
+};
+
+export const t = {
+  string: () => createPinBuilder('string'),
+  number: () => createPinBuilder('number'),
+  boolean: () => createPinBuilder('boolean'),
+  any: () => createPinBuilder('any'),
+  object: (name = '') => {
+    const normalized = normalizeString(name);
+    return createPinBuilder(normalized ? `object:${normalized}` : 'object');
+  },
+  enumValue: (name) => {
+    const normalized = normalizeString(name);
+    return createPinBuilder(normalized ? `enum-value:${normalized}` : 'enum-value');
+  },
+  struct: (name) => {
+    const normalized = normalizeString(name);
+    if (!normalized) {
+      throw new Error('t.struct(name): "name" is required');
+    }
+    return createPinBuilder(`object:${normalized}`);
+  },
+  array: (innerTypeBuilder) => {
+    if (!(innerTypeBuilder instanceof PinBuilder)) {
+      throw new Error('t.array(inner): inner must be a Brickr type builder (e.g. t.string())');
+    }
+    const baseType = normalizeString(innerTypeBuilder._type, 'any') || 'any';
+    return createPinBuilder(baseType.endsWith(':array') ? baseType : `${baseType}:array`);
+  }
+};
+
+export const buildManifestFromNode = (nodeDefinition) => {
+  const normalized = buildNodeDefinition(nodeDefinition);
+  return {
+    nodeKey: normalized.nodeKey,
+    name: normalized.name,
+    description: normalized.description,
+    category: normalized.category,
+    inputs: normalized.inputs,
+    outputs: normalized.outputs
+  };
+};
+
+export const collectAssets = (assets = []) => {
+  const all = Array.isArray(assets) ? assets : [assets];
+  return all.reduce((acc, item) => {
+    if (!item || typeof item !== 'object') return acc;
+    if (item.__brickrType === 'enum') acc.enums.push(item);
+    if (item.__brickrType === 'structure') acc.structures.push(item);
+    if (item.__brickrType === 'secret') acc.secrets.push(item);
+    return acc;
+  }, { enums: [], structures: [], secrets: [] });
+};