YepCode Coding Rules

This file provides guidelines for LLMs to write source code compatible with the YepCode platform and ready to use it’s specific helpers.

Download this file

What is YepCode?

YepCode is an enterprise-ready integration and automation platform that offers comprehensive features for API integrations, workflow automation, and data processing. It excels in providing enterprise-grade sandboxing and security measures specifically designed for running code generated by LLMs.

This offers developers a familiar coding environment, while handling all the infrastructure concerns, security measures, and dependency management automatically.

Core Concepts

Processes

• Basic unit of execution in YepCode
• Contains business logic written in JavaScript (NodeJS v22) or Python (v3.13)
• Each process may have input parameters, that are defined using a JSON Schema file (parametersSchema.json) and can be accessed during execution using the yepcode.context.parameters object
• If you use the YepCode CLI, the copy of your YepCode workspace in your local environment will have the following folder structure:

  📦 <workspace-name>
  ┣ 📂 dependencies
  ┃ ┣ 📜 package.json
  ┃ ┣ 📜 requirements.txt
  ┣ 📂 modules
  ┃ ┣ 📂 <javascript-module-slug>
  ┃ ┃ ┗ 📜 <module-slug>.js
  ┃ ┣ 📂 <python-module-slug>
  ┃ ┃ ┗ 📜 <module-slug>.py
  ┃ ┣ 📂 <module-with-versions>
  ┃ ┃ ┣ 📂 versions
  ┃ ┃ ┃ ┣ 📂 v1.0
  ┃ ┃ ┃ ┃ ┗ 📜 <module-slug>.js
  ┃ ┃ ┃ ┗ 📂 ...
  ┃ ┃ ┗ 📜 <module-slug>.js
  ┃ ┗ 📂 ...
  ┣ 📂 processes
  ┃ ┣ 📂 <javascript-process-slug>
  ┃ ┃ ┣ 📜 README.md
  ┃ ┃ ┣ 📜 index.js
  ┃ ┃ ┣ 📜 parametersSchema.json
  ┃ ┃ ┗ 📜 parameters.json
  ┃ ┣ 📂 <python-process-slug>
  ┃ ┃ ┣ 📜 README.md
  ┃ ┃ ┣ 📜 main.py
  ┃ ┃ ┣ 📜 parametersSchema.json
  ┃ ┃ ┗ 📜 parameters.json
  ┃ ┣ 📂 <process-slug-with-versions>
  ┃ ┃ ┣ 📂 versions
  ┃ ┃ ┃ ┣ 📂 v1.0
  ┃ ┃ ┃ ┃ ┣ 📜 README.md
  ┃ ┃ ┃ ┃ ┣ 📜 index.js
  ┃ ┃ ┃ ┃ ┣ 📜 parametersSchema.json
  ┃ ┃ ┃ ┃ ┗ 📜 parameters.json
  ┃ ┃ ┃ ┗ 📂 ...
  ┃ ┃ ┣ 📜 README.md
  ┃ ┃ ┣ 📜 index.js
  ┃ ┃ ┣ 📜 parametersSchema.json
  ┃ ┃ ┗ 📜 parameters.json
  ┃ ┗ 📂 ...
  ┣ 📜 datastore.json
  ┣ 📜 variables.env
  ┣ 📜 variables.local.env
  ┣ 📜 .gitignore
  ┗ 📂 .yepcode

  - `dependencies`: Dependencies' source code, containing both the python and javascript dependencies.
    - `package.json`: It will be a json file with the dependencies for the javascript dependencies. Just the content of the dependencies field in any standard package.json file.
    - `requirements.txt`: Python requirements.txt file with the dependencies for the python dependencies.
  - `processes`: Processes' source code, with one folder per process, containing process files.
    - `README.md`: Markdown file with the process description.
    - `index.js` or `index.py`: Process source code in JavaScript or Python.
    - `parametersSchema.json`: Parameters schema JSON file.
    - `parameters.json`: Sample input file dynamically generated. It will be used as default input file in local executions, but you may provide another one.
    - `versions`: if process has published versions, a new folder will exists and each version folder will have a process replica with the published contents.
  - `modules`: Modules' source code, with one folder per module, containing the module file.
    - `versions`: if module has published versions, a new folder will exists and each version folder will have a module replica with the published contents.
  - `variables.env`: Includes all team variables in .env file format (KEY=VALUE).
  - `variables.local.env`: Local environment variables that override `variables.env`.
  - `datastore.json`: YepCode datastore file.
  - `.gitignore`: Auto generated gitignore file. It will be used if you create a git repo for this directory to ignore sensitive resources (variables .env).
  - `.yepcode`: YepCode workspace metadata directory.

Modules

• Reusable code libraries shared across processes
• Help maintain DRY (Don’t Repeat Yourself) principle
• Support versioning for better code management

Execution Context

• Each process runs in an isolated environment
• Has access to:
  • Input parameters
  • Environment variables
  • Execution metadata
  • Process information
  • Team settings
  • Request data (for webhooks)

Team Variables

• Key-value pairs available across processes
• Can store sensitive information securely
• Accessible via environment variables or yepcode.env

Datastore

• Key-value storage system for data persistence
• Share data between process executions
• Available in paid plans with specific limits
• Useful for maintaining state and caching
• Can only store strings or numbers. If you need to store other types of data, you should convert them to strings before storing them.

General Rules

• Follow the language-specific code style guidelines
• Handle errors appropriately and provide meaningful error messages (errors may be thrown for failed executions)
• Use logging for debugging and tracking execution state
• Validate input parameters when needed
• Use environment variables for sensitive data
• Do not use hardcoded values and suggest to change it to input parameters or to env vars
• Use appropriate status codes for responses

JavaScript Rules

Code Structure (JavaScript)

• Use NodeJS v20 features
• Wrap code in async function for await support
• Export functions using module.exports for modules
• Use ES6+ features when appropriate

Code Template (JavaScript)

async function main() {
  // Access input parameters
  const { parameters } = yepcode.context;

  // Your code here

  // Return result
  return { "message": "Success!" };
}

module.exports = { main };

Helpers Usage (JavaScript)

• Access execution info: const { id, comment } = yepcode.execution;
• Access process info: const { id: processId, name: processName } = yepcode.execution.process;
• Access schedule info: const { id: scheduleId, comment: scheduleComment } = yepcode.execution.schedule;
• Access team timezone: const timezone = yepcode.execution.timezone;
• Use environment variables: const apiKey = process.env.API_KEY // (or yepcode.env.API_KEY);
• Import YepCode modules: const { myFunc } = yepcode.import("module-name");
  • Caution: you can’t use variables as module names, just hardcoded strings
• Import YepCode modules with specific version: const { myFunc } = yepcode.import("module-name", "v1.0");
• Run another process: await yepcode.processes.run("process-identifier", options);

Logging (JavaScript)

console.log('INFO message');
console.debug('DEBUG message');
console.info('INFO message');
console.warn('WARNING message');
console.error('ERROR message');

Dependencies Management (JavaScript)

• You may use external npm packages
• Just add the require statement to the code and the package will be installed automatically
• If package import name is different than the package name, you must use the the add-package comment:

// @add-package axios
const axios = require('axios');

Local Disk (JavaScript)

const path = require('path');

// Calculate the path to the temporary file
const filePath = path.join(process.env.TMP_DATA_DIR, 'myfile.txt');

// Writing a file
const fs = require('fs');
fs.writeFileSync(filePath, 'Hello from YepCode!');

Datastore (JavaScript)

// Setting a value
await yepcode.datastore.set("key", "value");
// Setting a object value
await yepcode.datastore.set("key", JSON.stringify({ "name": "John", "age": 30 }));

// Getting a value
const value = await yepcode.datastore.get("key");

// Deleting a value
await yepcode.datastore.del("key");

Storage (JavaScript)

const path = require("node:path");
const localPath = path.join(process.env.TMP_DATA_DIR, "localfile.txt");

// Uploading a file
await yepcode.storage.upload("path/myfile.txt", fs.createReadStream(localPath));

// Listing files
const files = await yepcode.storage.list();

// Downloading a file
const stream = await yepcode.storage.download("path/myfile.txt");
stream.pipe(fs.createWriteStream(localPath));

// Deleting a file
await yepcode.storage.delete("path/myfile.txt");

Return Values (JavaScript)

Standard Return

return { "message": "Success!" };

Custom HTTP Status Codes

• This is the format for custom HTTP status codes:

return {
    status: 404,
    body: { "message": "Not found" },
    headers: { "Content-Type": "application/json" }

Transient Results (JavaScript)

return {
    transient: true,
    data: sensitiveData
};

Python Rules

Code Structure (Python)

• Use Python 3.13 features
• Define main() function for debugging support
• Use type hints when appropriate
• Follow PEP 8 style guidelines

Code Template (Python)

def main():
    # Access input parameters
    parameters = yepcode.context.parameters

    # Your code here

    # Return result
    return { "message": "Success!" }

Helpers Usage (Python)

• Access execution info: id, comment = yepcode.execution.id, yepcode.execution.comment
• Access process info: processId, processName = yepcode.execution.process.id, yepcode.execution.process.name
• Access schedule info: scheduleId, scheduleComment = yepcode.execution.get("schedule", {}).values()
• Access team timezone: timezone = yepcode.execution.timezone
• Use environment variables: api_key = os.getenv("API_KEY") # (or yepcode.env.API_KEY)
• Import YepCode modules: my_func = yepcode.import_module("module-name")
  • Caution: you can’t use variables as module names, just hardcoded strings
• Import YepCode modules with specific version: my_func = yepcode.import_module("module-name", "v1.0")
• Run another process: yepcode.processes.run("process-identifier", options)

Logging (Python)

print("INFO message")  # Generates INFO level log
logger.debug("DEBUG message")
logger.info("INFO message")
logger.warn("WARNING message")
logger.error("ERROR message")

Dependencies Management (Python)

• You may use external npm packages
• Just add the require statement to the code and the package will be installed automatically
• If package import name is different than the package name, you must use the the add-package comment:

# @add-package requests
import requests

Local Disk (Python)

import os

# Calculate the path to the temporary file
file_path = os.path.join(os.environ.get("TMP_DATA_DIR"), "myfile.txt")

# Writing a file
with open(file_path, 'w') as f:
    f.write('Hello from YepCode!')

Datastore (Python)

# Setting a value
yepcode.datastore.set("key", "value");

# Setting a object value
yepcode.datastore.set("key", json.dumps({ "name": "John", "age": 30 }));

# Getting a value
value = yepcode.datastore.get("key");

# Deleting a value
yepcode.datastore.delete("key");

Storage (Python)

import os
local_path = os.path.join(os.environ.get("TMP_DATA_DIR"), "localfile.txt")

// Uploading a file
with open(local_path, "rb") as f:
    obj = yepcode.storage.upload("path/myfile.txt", f)
    print("Uploaded:", obj.name, obj.size, obj.link)


// Listing files
objects = yepcode.storage.list()

// Downloading a file
content = yepcode.storage.download("path/myfile.txt")
with open(local_path, "wb") as f:
    f.write(content)

// Deleting a file
yepcode.storage.delete("path/myfile.txt")

Return Values (Python)

Standard Return

return { "message": "Success!" }

Custom HTTP Status Codes

• This is the format for custom HTTP status codes:

return {
    "status": 404,
    "body": { "message": "Not found" },
    "headers": { "Content-Type": "application/json" }
}

Transient Results (Python)

return {
    "transient": True,
    "data": sensitive_data
}