2044 lines
27 KiB
Markdown
2044 lines
27 KiB
Markdown
# API Documentation
|
|
|
|
Contract version: 0.3.1
|
|
|
|
This reference documents the Lua runtime API available through `bds` in embedded bDS2 scripts.
|
|
|
|
`bds` is available in project-scoped Lua scripts executed through the bDS2 scripting runtime.
|
|
|
|
## Usage
|
|
|
|
```lua
|
|
local project = bds.projects.get_active()
|
|
local meta = bds.meta.get_project_metadata()
|
|
```
|
|
|
|
## Table of contents
|
|
|
|
- [app](#app)
|
|
- [projects](#projects)
|
|
- [posts](#posts)
|
|
- [media](#media)
|
|
- [scripts](#scripts)
|
|
- [templates](#templates)
|
|
- [meta](#meta)
|
|
- [tags](#tags)
|
|
- [tasks](#tasks)
|
|
- [sync](#sync)
|
|
- [publish](#publish)
|
|
- [chat](#chat)
|
|
- [embeddings](#embeddings)
|
|
- [Data Structures](#data-structures)
|
|
|
|
## app
|
|
|
|
### app.get_data_paths
|
|
|
|
Return filesystem paths for the current application and project data.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.app.get_data_paths()
|
|
```
|
|
|
|
### app.get_default_project_path
|
|
|
|
Return the current project's filesystem path.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `string | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.app.get_default_project_path()
|
|
```
|
|
|
|
### app.get_system_language
|
|
|
|
Return the current UI locale.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `string | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.app.get_system_language()
|
|
```
|
|
|
|
### app.read_project_metadata
|
|
|
|
Read project metadata from a project folder path.
|
|
|
|
**Parameters**
|
|
|
|
- folder_path (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ProjectMetadata | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.app.read_project_metadata("value")
|
|
```
|
|
|
|
|
|
## chat
|
|
|
|
### chat.analyze_media_image
|
|
|
|
Analyze a media image using the configured AI runtime.
|
|
|
|
**Parameters**
|
|
|
|
- media_id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.chat.analyze_media_image("value")
|
|
```
|
|
|
|
### chat.analyze_post
|
|
|
|
Analyze a post using the configured AI runtime.
|
|
|
|
**Parameters**
|
|
|
|
- post_id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.chat.analyze_post("value")
|
|
```
|
|
|
|
### chat.detect_media_language
|
|
|
|
Detect the language of media metadata.
|
|
|
|
**Parameters**
|
|
|
|
- title (string, required)
|
|
- alt (string, optional)
|
|
- caption (string, optional)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.chat.detect_media_language("value", "value", "value")
|
|
```
|
|
|
|
### chat.detect_post_language
|
|
|
|
Detect the language of post title and content.
|
|
|
|
**Parameters**
|
|
|
|
- title (string, required)
|
|
- content (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.chat.detect_post_language("value", "value")
|
|
```
|
|
|
|
### chat.translate_media_metadata
|
|
|
|
Translate media metadata and persist the translation.
|
|
|
|
**Parameters**
|
|
|
|
- media_id (string, required)
|
|
- language (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.chat.translate_media_metadata("value", "value")
|
|
```
|
|
|
|
### chat.translate_post
|
|
|
|
Translate a post and persist the translation.
|
|
|
|
**Parameters**
|
|
|
|
- post_id (string, required)
|
|
- language (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.chat.translate_post("value", "value")
|
|
```
|
|
|
|
|
|
## embeddings
|
|
|
|
### embeddings.compute_similarities
|
|
|
|
Compute similarity scores from one source post to target posts.
|
|
|
|
**Parameters**
|
|
|
|
- post_id (string, required)
|
|
- target_ids (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.embeddings.compute_similarities("value", {})
|
|
```
|
|
|
|
### embeddings.dismiss_pair
|
|
|
|
Dismiss a duplicate candidate pair.
|
|
|
|
**Parameters**
|
|
|
|
- post_id_a (string, required)
|
|
- post_id_b (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.embeddings.dismiss_pair("value", "value")
|
|
```
|
|
|
|
### embeddings.find_duplicates
|
|
|
|
Find duplicate post candidates for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.embeddings.find_duplicates()
|
|
```
|
|
|
|
### embeddings.find_similar
|
|
|
|
Find posts similar to the given post id.
|
|
|
|
**Parameters**
|
|
|
|
- post_id (string, required)
|
|
- limit (integer, optional)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.embeddings.find_similar("value", 1)
|
|
```
|
|
|
|
### embeddings.get_progress
|
|
|
|
Get embedding index progress for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.embeddings.get_progress()
|
|
```
|
|
|
|
### embeddings.index_unindexed_posts
|
|
|
|
Index posts missing embeddings for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.embeddings.index_unindexed_posts()
|
|
```
|
|
|
|
### embeddings.suggest_tags
|
|
|
|
Suggest tags for a post from semantic similarity.
|
|
|
|
**Parameters**
|
|
|
|
- post_id (string, required)
|
|
- exclude_tags (table, optional)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.embeddings.suggest_tags("value", {})
|
|
```
|
|
|
|
|
|
## media
|
|
|
|
### media.import
|
|
|
|
Import media into the current project.
|
|
|
|
**Parameters**
|
|
|
|
- data (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `MediaData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.media.import({})
|
|
```
|
|
|
|
### media.update
|
|
|
|
Update media metadata by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
- data (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `MediaData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.media.update("value", {})
|
|
```
|
|
|
|
### media.delete
|
|
|
|
Delete a media item by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.media.delete("value")
|
|
```
|
|
|
|
### media.get
|
|
|
|
Fetch one media item by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `MediaData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.media.get("value")
|
|
```
|
|
|
|
### media.get_all
|
|
|
|
Fetch all media in the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `MediaData[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.media.get_all()
|
|
```
|
|
|
|
|
|
## meta
|
|
|
|
### meta.add_category
|
|
|
|
Add a category to the current project.
|
|
|
|
**Parameters**
|
|
|
|
- name (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ProjectMetadata | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.meta.add_category("value")
|
|
```
|
|
|
|
### meta.add_tag
|
|
|
|
Add a tag record to the current project if it does not already exist.
|
|
|
|
**Parameters**
|
|
|
|
- name (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `string[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.meta.add_tag("value")
|
|
```
|
|
|
|
### meta.clear_publishing_preferences
|
|
|
|
Reset publishing preferences to defaults.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.meta.clear_publishing_preferences()
|
|
```
|
|
|
|
### meta.get_categories
|
|
|
|
Get project categories.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `string[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.meta.get_categories()
|
|
```
|
|
|
|
### meta.get_project_metadata
|
|
|
|
Read metadata for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ProjectMetadata`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.meta.get_project_metadata()
|
|
```
|
|
|
|
### meta.get_publishing_preferences
|
|
|
|
Get publishing preferences for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.meta.get_publishing_preferences()
|
|
```
|
|
|
|
### meta.get_tags
|
|
|
|
Get tag names for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `string[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.meta.get_tags()
|
|
```
|
|
|
|
### meta.remove_category
|
|
|
|
Remove a category from the current project.
|
|
|
|
**Parameters**
|
|
|
|
- name (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ProjectMetadata | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.meta.remove_category("value")
|
|
```
|
|
|
|
### meta.remove_tag
|
|
|
|
Remove a tag record from the current project by name.
|
|
|
|
**Parameters**
|
|
|
|
- name (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `string[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.meta.remove_tag("value")
|
|
```
|
|
|
|
### meta.set_project_metadata
|
|
|
|
Replace project metadata fields for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- updates (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ProjectMetadata | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.meta.set_project_metadata({})
|
|
```
|
|
|
|
### meta.set_publishing_preferences
|
|
|
|
Set publishing preferences for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- prefs (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.meta.set_publishing_preferences({})
|
|
```
|
|
|
|
### meta.update_project_metadata
|
|
|
|
Update metadata for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- updates (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ProjectMetadata | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.meta.update_project_metadata({})
|
|
```
|
|
|
|
|
|
## posts
|
|
|
|
### posts.create
|
|
|
|
Create a post in the current project.
|
|
|
|
**Parameters**
|
|
|
|
- data (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `PostData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.create({})
|
|
```
|
|
|
|
### posts.update
|
|
|
|
Update a post by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
- data (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `PostData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.update("value", {})
|
|
```
|
|
|
|
### posts.delete
|
|
|
|
Delete a post by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.delete("value")
|
|
```
|
|
|
|
### posts.get
|
|
|
|
Fetch one post by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `PostData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.get("value")
|
|
```
|
|
|
|
### posts.get_all
|
|
|
|
Fetch all posts in the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `PostData[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.get_all()
|
|
```
|
|
|
|
### posts.get_by_slug
|
|
|
|
Fetch one post by slug.
|
|
|
|
**Parameters**
|
|
|
|
- slug (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `PostData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.get_by_slug("value")
|
|
```
|
|
|
|
### posts.get_categories
|
|
|
|
Get category names used by posts in the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `string[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.get_categories()
|
|
```
|
|
|
|
### posts.get_categories_with_counts
|
|
|
|
Get post categories with usage counts.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.get_categories_with_counts()
|
|
```
|
|
|
|
### posts.get_tags
|
|
|
|
Get tag names used by posts in the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `string[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.get_tags()
|
|
```
|
|
|
|
### posts.get_tags_with_counts
|
|
|
|
Get post tags with usage counts.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.get_tags_with_counts()
|
|
```
|
|
|
|
### posts.get_translation
|
|
|
|
Get a single translation for a post by language.
|
|
|
|
**Parameters**
|
|
|
|
- post_id (string, required)
|
|
- language (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.get_translation("value", "value")
|
|
```
|
|
|
|
### posts.get_translations
|
|
|
|
Get all translations for a post.
|
|
|
|
**Parameters**
|
|
|
|
- post_id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.get_translations("value")
|
|
```
|
|
|
|
### posts.has_published_version
|
|
|
|
Check whether a post has a published version.
|
|
|
|
**Parameters**
|
|
|
|
- post_id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.has_published_version("value")
|
|
```
|
|
|
|
### posts.publish
|
|
|
|
Publish a post by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `PostData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.publish("value")
|
|
```
|
|
|
|
### posts.rebuild_from_files
|
|
|
|
Rebuild post records from published files.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `PostData[] | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.rebuild_from_files()
|
|
```
|
|
|
|
### posts.reindex_text
|
|
|
|
Reindex post and media search text for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.reindex_text()
|
|
```
|
|
|
|
### posts.search
|
|
|
|
Search posts by free-text query.
|
|
|
|
**Parameters**
|
|
|
|
- query (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `PostData[] | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.posts.search("value")
|
|
```
|
|
|
|
|
|
## projects
|
|
|
|
### projects.create
|
|
|
|
Create a project.
|
|
|
|
**Parameters**
|
|
|
|
- data (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ProjectData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.projects.create({})
|
|
```
|
|
|
|
### projects.delete
|
|
|
|
Delete a project by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.projects.delete("value")
|
|
```
|
|
|
|
### projects.delete_with_data
|
|
|
|
Delete a project by id and remove its project directory.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.projects.delete_with_data("value")
|
|
```
|
|
|
|
### projects.get
|
|
|
|
Fetch one project by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ProjectData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.projects.get("value")
|
|
```
|
|
|
|
### projects.get_all
|
|
|
|
Fetch all projects.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ProjectData[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.projects.get_all()
|
|
```
|
|
|
|
### projects.get_active
|
|
|
|
Fetch the active project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ProjectData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.projects.get_active()
|
|
```
|
|
|
|
### projects.set_active
|
|
|
|
Set the active project by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ProjectData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.projects.set_active("value")
|
|
```
|
|
|
|
### projects.update
|
|
|
|
Update a project by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
- data (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ProjectData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.projects.update("value", {})
|
|
```
|
|
|
|
|
|
## publish
|
|
|
|
### publish.upload_site
|
|
|
|
Upload the rendered site using the provided publishing credentials.
|
|
|
|
**Parameters**
|
|
|
|
- credentials (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TaskData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.publish.upload_site({})
|
|
```
|
|
|
|
|
|
## scripts
|
|
|
|
### scripts.create
|
|
|
|
Create a script in the current project.
|
|
|
|
**Parameters**
|
|
|
|
- data (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ScriptData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.scripts.create({})
|
|
```
|
|
|
|
### scripts.update
|
|
|
|
Update a script by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
- data (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ScriptData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.scripts.update("value", {})
|
|
```
|
|
|
|
### scripts.delete
|
|
|
|
Delete a script by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.scripts.delete("value")
|
|
```
|
|
|
|
### scripts.get
|
|
|
|
Fetch one script by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ScriptData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.scripts.get("value")
|
|
```
|
|
|
|
### scripts.get_all
|
|
|
|
Fetch all scripts in the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ScriptData[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.scripts.get_all()
|
|
```
|
|
|
|
### scripts.publish
|
|
|
|
Publish a script by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ScriptData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.scripts.publish("value")
|
|
```
|
|
|
|
### scripts.rebuild_from_files
|
|
|
|
Rebuild script records from published files.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ScriptData[] | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.scripts.rebuild_from_files()
|
|
```
|
|
|
|
|
|
## sync
|
|
|
|
### sync.check_availability
|
|
|
|
Return whether Git is available on the current machine.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.sync.check_availability()
|
|
```
|
|
|
|
### sync.commit_all
|
|
|
|
Commit all pending repository changes for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- message (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.sync.commit_all("value")
|
|
```
|
|
|
|
### sync.fetch
|
|
|
|
Fetch remote Git refs for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.sync.fetch()
|
|
```
|
|
|
|
### sync.get_history
|
|
|
|
Return commit history for the current project repository.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.sync.get_history()
|
|
```
|
|
|
|
### sync.get_remote_state
|
|
|
|
Return remote repository state information for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.sync.get_remote_state()
|
|
```
|
|
|
|
### sync.get_repo_state
|
|
|
|
Return repository state information for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.sync.get_repo_state()
|
|
```
|
|
|
|
### sync.get_status
|
|
|
|
Return Git status information for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.sync.get_status()
|
|
```
|
|
|
|
### sync.pull
|
|
|
|
Pull remote changes for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.sync.pull()
|
|
```
|
|
|
|
### sync.push
|
|
|
|
Push local changes for the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.sync.push()
|
|
```
|
|
|
|
|
|
## tags
|
|
|
|
### tags.create
|
|
|
|
Create a tag in the current project.
|
|
|
|
**Parameters**
|
|
|
|
- data (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TagData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tags.create({})
|
|
```
|
|
|
|
### tags.update
|
|
|
|
Update a tag by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
- data (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TagData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tags.update("value", {})
|
|
```
|
|
|
|
### tags.delete
|
|
|
|
Delete a tag by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tags.delete("value")
|
|
```
|
|
|
|
### tags.get
|
|
|
|
Fetch one tag by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TagData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tags.get("value")
|
|
```
|
|
|
|
### tags.get_all
|
|
|
|
Fetch all tags in the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TagData[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tags.get_all()
|
|
```
|
|
|
|
### tags.get_by_name
|
|
|
|
Fetch one tag by name.
|
|
|
|
**Parameters**
|
|
|
|
- name (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TagData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tags.get_by_name("value")
|
|
```
|
|
|
|
### tags.get_posts_with_tag
|
|
|
|
Get post ids using a specific tag.
|
|
|
|
**Parameters**
|
|
|
|
- tag_id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `string[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tags.get_posts_with_tag("value")
|
|
```
|
|
|
|
### tags.get_with_counts
|
|
|
|
Fetch tags with usage counts.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `table[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tags.get_with_counts()
|
|
```
|
|
|
|
### tags.merge
|
|
|
|
Merge source tags into a target tag.
|
|
|
|
**Parameters**
|
|
|
|
- source_tag_ids (table, required)
|
|
- target_tag_id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tags.merge({}, "value")
|
|
```
|
|
|
|
### tags.rename
|
|
|
|
Rename a tag by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
- new_name (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TagData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tags.rename("value", "value")
|
|
```
|
|
|
|
### tags.sync_from_posts
|
|
|
|
Sync tag records from post tags.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TagData[] | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tags.sync_from_posts()
|
|
```
|
|
|
|
|
|
## tasks
|
|
|
|
### tasks.cancel
|
|
|
|
Cancel a task by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tasks.cancel("value")
|
|
```
|
|
|
|
### tasks.clear_completed
|
|
|
|
Clear completed tasks from the in-memory task list.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tasks.clear_completed()
|
|
```
|
|
|
|
### tasks.get
|
|
|
|
Fetch one task by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TaskData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tasks.get("value")
|
|
```
|
|
|
|
### tasks.get_all
|
|
|
|
Fetch all tasks currently tracked by the task manager.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TaskData[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tasks.get_all()
|
|
```
|
|
|
|
### tasks.get_running
|
|
|
|
Fetch running tasks currently tracked by the task manager.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TaskData[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tasks.get_running()
|
|
```
|
|
|
|
### tasks.status_snapshot
|
|
|
|
Fetch the current task status snapshot.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TaskStatus`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.tasks.status_snapshot()
|
|
```
|
|
|
|
|
|
## templates
|
|
|
|
### templates.create
|
|
|
|
Create a template in the current project.
|
|
|
|
**Parameters**
|
|
|
|
- data (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TemplateData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.templates.create({})
|
|
```
|
|
|
|
### templates.update
|
|
|
|
Update a template by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
- data (table, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TemplateData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.templates.update("value", {})
|
|
```
|
|
|
|
### templates.delete
|
|
|
|
Delete a template by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `boolean`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.templates.delete("value")
|
|
```
|
|
|
|
### templates.get
|
|
|
|
Fetch one template by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TemplateData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.templates.get("value")
|
|
```
|
|
|
|
### templates.get_all
|
|
|
|
Fetch all templates in the current project.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TemplateData[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.templates.get_all()
|
|
```
|
|
|
|
### templates.get_enabled_by_kind
|
|
|
|
Fetch enabled templates filtered by kind.
|
|
|
|
**Parameters**
|
|
|
|
- kind (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TemplateData[]`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.templates.get_enabled_by_kind("value")
|
|
```
|
|
|
|
### templates.publish
|
|
|
|
Publish a template by id.
|
|
|
|
**Parameters**
|
|
|
|
- id (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TemplateData | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.templates.publish("value")
|
|
```
|
|
|
|
### templates.rebuild_from_files
|
|
|
|
Rebuild template records from published files.
|
|
|
|
**Parameters**
|
|
|
|
- None
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `TemplateData[] | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.templates.rebuild_from_files()
|
|
```
|
|
|
|
### templates.validate
|
|
|
|
Validate Liquid template syntax.
|
|
|
|
**Parameters**
|
|
|
|
- content (string, required)
|
|
|
|
**Response specification**
|
|
|
|
- Return type: `ValidationResult | nil`
|
|
|
|
**Example call**
|
|
|
|
```lua
|
|
local result = bds.templates.validate("value")
|
|
```
|
|
|
|
|
|
|
|
## Data Structures
|
|
|
|
### ProjectData
|
|
|
|
Project record stored in the application database.
|
|
|
|
- `id`: `string`
|
|
- `name`: `string`
|
|
- `slug`: `string`
|
|
- `description`: `string | nil`
|
|
- `data_path`: `string | nil`
|
|
- `is_active`: `boolean`
|
|
- `created_at`: `integer`
|
|
- `updated_at`: `integer`
|
|
|
|
### ProjectMetadata
|
|
|
|
Current project metadata and publishing settings snapshot.
|
|
|
|
- `name`: `string`
|
|
- `description`: `string | nil`
|
|
- `public_url`: `string | nil`
|
|
- `main_language`: `string | nil`
|
|
- `default_author`: `string | nil`
|
|
- `categories`: `string[]`
|
|
- `blog_languages`: `string[]`
|
|
- `publishing_preferences`: `table`
|
|
|
|
### PostData
|
|
|
|
Post record with link graph data added for scripting.
|
|
|
|
- `id`: `string`
|
|
- `project_id`: `string`
|
|
- `title`: `string`
|
|
- `slug`: `string`
|
|
- `status`: `string`
|
|
- `language`: `string | nil`
|
|
- `tags`: `string[]`
|
|
- `categories`: `string[]`
|
|
- `backlinks`: `table[]`
|
|
- `links_to`: `table[]`
|
|
|
|
### MediaData
|
|
|
|
Media record stored for a project.
|
|
|
|
- `id`: `string`
|
|
- `project_id`: `string`
|
|
- `original_name`: `string`
|
|
- `mime_type`: `string`
|
|
- `file_path`: `string`
|
|
- `title`: `string | nil`
|
|
- `alt`: `string | nil`
|
|
- `caption`: `string | nil`
|
|
- `tags`: `string[]`
|
|
|
|
### ScriptData
|
|
|
|
Lua script record.
|
|
|
|
- `id`: `string`
|
|
- `project_id`: `string`
|
|
- `slug`: `string`
|
|
- `title`: `string`
|
|
- `kind`: `string`
|
|
- `entrypoint`: `string`
|
|
- `enabled`: `boolean`
|
|
- `status`: `string`
|
|
|
|
### TemplateData
|
|
|
|
Template record for site rendering.
|
|
|
|
- `id`: `string`
|
|
- `project_id`: `string`
|
|
- `slug`: `string`
|
|
- `title`: `string`
|
|
- `kind`: `string`
|
|
- `enabled`: `boolean`
|
|
- `status`: `string`
|
|
|
|
### TagData
|
|
|
|
Tag record stored for a project.
|
|
|
|
- `id`: `string`
|
|
- `project_id`: `string`
|
|
- `name`: `string`
|
|
- `color`: `string | nil`
|
|
- `post_template_slug`: `string | nil`
|
|
|
|
### TaskData
|
|
|
|
Public task snapshot returned by the task manager.
|
|
|
|
- `id`: `string`
|
|
- `name`: `string`
|
|
- `status`: `string`
|
|
- `progress`: `number | table | nil`
|
|
- `message`: `string | nil`
|
|
|
|
### TaskStatus
|
|
|
|
Aggregate task status snapshot.
|
|
|
|
- `active_count`: `integer`
|
|
- `running_count`: `integer`
|
|
- `pending_count`: `integer`
|
|
- `tasks`: `TaskData[]`
|
|
|
|
### ValidationResult
|
|
|
|
Template validation result.
|
|
|
|
- `valid`: `boolean`
|
|
- `errors`: `string[]`
|