API Reference

This section is generated automatically from C++ documentation comments via Doxygen (XML) + Sphinx (Breathe).

class Artifact

#include <artifact.hpp>

A file reference within a revision in the Kumiho system.

Artifacts point to actual files on local disk, network storage, or cloud URIs. Kumiho tracks the path and metadata but does not upload or modify the files.

The artifact’s kref includes both revision and artifact name: kref://project/space/item.kind?r=1&a=artifact_name

Example:

auto mesh = revision->createArtifact("mesh", "/assets/hero.fbx");
auto textures = revision->createArtifact("textures", "smb://server/tex/hero/");

// Set metadata
mesh->setMetadata({{"triangles", "2.5M"}, {"format", "FBX 2020"}});

// Set as default artifact
mesh->setDefault();

Public Functions

Artifact(const ::kumiho::ArtifactResponse &response, Client *client)

Construct an Artifact from a protobuf response.

Parameters:

• response – The protobuf ArtifactResponse message.

• client – The client for making API calls.

Kref getKref() const

Get the artifact’s unique Kref.

Returns:

The Kref URI for this artifact.

std::string getName() const

Get the artifact name.

Returns:

The name of this artifact (e.g., “mesh”, “textures”).

std::string getLocation() const

Get the file location.

Returns:

The file path or URI where the artifact is stored.

Kref getRevisionKref() const

Get the parent revision’s Kref.

Returns:

The Kref of the revision containing this artifact.

Kref getItemKref() const

Get the parent item’s Kref.

Returns:

The Kref of the item containing this artifact.

Metadata getMetadata() const

Get the artifact’s metadata.

Returns:

A map of metadata key-value pairs.

std::optional<std::string> getCreatedAt() const

Get the creation timestamp.

Returns:

ISO timestamp when the artifact was created, or nullopt.

std::string getAuthor() const

Get the author’s user ID.

Returns:

The UUID of the user who created the artifact.

std::string getUsername() const

Get the author’s display name.

Returns:

The username of the artifact creator.

bool isDeprecated() const

Check if the artifact is deprecated.

Returns:

True if deprecated, false otherwise.

std::shared_ptr<Artifact> setMetadata(const Metadata &metadata)

Set or update metadata for this artifact.

Metadata is merged with existing metadata—existing keys are overwritten and new keys are added.

Parameters:

metadata – Dictionary of metadata key-value pairs.

Returns:

The updated Artifact.

std::optional<std::string> getAttribute(const std::string &key)

Get a single metadata attribute.

Parameters:

key – The attribute key to retrieve.

Returns:

The attribute value, or nullopt if not found.

bool setAttribute(const std::string &key, const std::string &value)

Set a single metadata attribute.

Parameters:

• key – The attribute key to set.

• value – The attribute value.

Returns:

True if the attribute was set successfully.

bool deleteAttribute(const std::string &key)

Delete a single metadata attribute.

Parameters:

key – The attribute key to delete.

Returns:

True if the attribute was deleted successfully.

void deleteArtifact(bool force = false)

Delete this artifact.

Parameters:

force – If true, permanently delete. If false, soft delete (deprecate).

std::shared_ptr<Revision> getRevision()

Get the parent revision.

Returns:

The Revision containing this artifact.

std::shared_ptr<Item> getItem()

Get the parent item.

Returns:

The Item containing this artifact.

std::shared_ptr<Space> getSpace()

Get the parent space.

Returns:

The Space containing this artifact’s item.

std::shared_ptr<Project> getProject()

Get the parent project.

Returns:

The Project containing this artifact.

void setDefault()

Set this artifact as the default for its revision.

When resolving a revision without specifying an artifact name, the default artifact’s location is returned.

std::shared_ptr<Artifact> setDeprecated(bool deprecated)

Set the deprecated status.

Parameters:

deprecated – True to deprecate, false to restore.

Returns:

The updated Artifact.

Kref getVersionKref() const

Alias for getRevisionKref().

Deprecated:

Use getRevisionKref() instead.

Kref getProductKref() const

Alias for getItemKref().

Deprecated:

Use getItemKref() instead.

void deleteResource(bool force = false)

Alias for deleteArtifact().

Deprecated:

Use deleteArtifact() instead.

std::shared_ptr<Revision> getVersion()

Alias for getRevision().

Deprecated:

Use getRevision() instead.

std::shared_ptr<Item> getProduct()

Alias for getItem().

Deprecated:

Use getItem() instead.

std::shared_ptr<Space> getGroup()

Alias for getSpace().

Deprecated:

Use getSpace() instead.

Private Members

::kumiho::ArtifactResponse response_

Client *client_

class AuthenticationError : public kumiho::api::KumihoError

#include <error.hpp>

Exception for authentication failures.

Thrown when authentication fails or credentials are invalid.

Public Functions

inline explicit AuthenticationError(const std::string &message)

class Bundle

#include <bundle.hpp>

An item that aggregates other items.

Bundles are special items (with kind “bundle”) that can contain references to other items. Each membership change creates a new revision, providing an immutable audit trail.

Note: The “bundle” item kind is reserved and cannot be created via createItem(). Use createBundle() instead.

Example:

// Create a bundle
auto bundle = project->createBundle("asset-bundle");

// Add items
auto hero_model = client->getItem("kref://project/models/hero.model");
bundle->addMember(hero_model);

// Get all members
for (const auto& member : bundle->getMembers()) {
    std::cout << "Item: " << member.item_kref.uri() << std::endl;
}

// View audit history
for (const auto& entry : bundle->getHistory()) {
    std::cout << "v" << entry.revision_number << ": " 
              << entry.action << std::endl;
}

Public Functions

Bundle(const ::kumiho::ItemResponse &response, Client *client)

Construct a Bundle from a protobuf response.

Parameters:

• response – The protobuf ItemResponse message.

• client – The client for making API calls.

Kref getKref() const

Get the bundle’s unique Kref.

Returns:

The Kref URI for this bundle.

std::string getName() const

Get the bundle name.

Returns:

The bundle name (without kind).

Metadata getMetadata() const

Get the bundle’s metadata.

Returns:

A map of metadata key-value pairs.

std::optional<std::string> getCreatedAt() const

Get the creation timestamp.

Returns:

ISO timestamp when the bundle was created, or nullopt.

std::string getAuthor() const

Get the author’s user ID.

Returns:

The UUID of the user who created the bundle.

std::string getUsername() const

Get the author’s display name.

Returns:

The username of the bundle creator.

bool isDeprecated() const

Check if the bundle is deprecated.

Returns:

True if deprecated, false otherwise.

std::shared_ptr<Bundle> addMember(const std::shared_ptr<Item> &item)

Add an item to this bundle.

Creates a new revision of the bundle with the membership change.

Parameters:

item – The item to add.

Returns:

The updated Bundle.

std::shared_ptr<Bundle> addMember(const Kref &item_kref)

Add an item to this bundle by Kref.

Parameters:

item_kref – The kref of the item to add.

Returns:

The updated Bundle.

std::shared_ptr<Bundle> removeMember(const std::shared_ptr<Item> &item)

Remove an item from this bundle.

Creates a new revision of the bundle with the membership change.

Parameters:

item – The item to remove.

Returns:

The updated Bundle.

std::shared_ptr<Bundle> removeMember(const Kref &item_kref)

Remove an item from this bundle by Kref.

Parameters:

item_kref – The kref of the item to remove.

Returns:

The updated Bundle.

std::vector<BundleMember> getMembers()

Get all current members of this bundle.

Returns:

A list of BundleMember objects.

std::vector<BundleRevisionHistory> getHistory()

Get the membership change history.

Returns all historical changes to the bundle’s membership, providing an immutable audit trail.

Returns:

A list of BundleRevisionHistory objects.

void deleteBundle(bool force = false)

Delete this bundle.

Parameters:

force – If true, permanently delete. If false, soft delete.

Private Members

::kumiho::ItemResponse response_

Client *client_

struct BundleMember

#include <bundle.hpp>

An item that is a member of a bundle.

Represents the membership relationship between an item and a bundle, including metadata about when and by whom the item was added.

Public Members

Kref item_kref

The kref of the member item.

std::string added_at

ISO timestamp when the item was added.

std::string added_by

UUID of the user who added the item.

std::string added_by_username

Display name of the user who added the item.

int added_in_revision

The bundle revision when this item was added.

struct BundleRevisionHistory

#include <bundle.hpp>

A historical change to a bundle’s membership.

Each entry captures a single add or remove operation, providing an immutable audit trail of all membership changes.

Public Members

int revision_number

The bundle revision number for this change.

std::string action

The action performed: “CREATED”, “ADDED”, or “REMOVED”.

std::optional<Kref> member_item_kref

The item that was added/removed (null for CREATED).

std::string author

UUID of the user who made the change.

std::string username

Display name of the user who made the change.

std::string created_at

ISO timestamp of the change.

Metadata metadata

Immutable metadata captured at the time of change.

struct CacheControl

#include <discovery.hpp>

Cache control metadata from the discovery response.

Tracks when the cache was issued, when it should be refreshed, and when it expires.

Public Functions

bool isExpired() const

Check if the cache entry has expired.

Returns:

True if expired, false otherwise.

bool shouldRefresh() const

Check if the cache entry should be proactively refreshed.

Returns:

True if refresh is recommended, false otherwise.

Public Members

std::chrono::system_clock::time_point issued_at

When the cache entry was issued.

std::chrono::system_clock::time_point refresh_at

When the cache should be proactively refreshed.

std::chrono::system_clock::time_point expires_at

When the cache entry expires and must be refreshed.

int expires_in_seconds

Total seconds until expiration.

int refresh_after_seconds

Seconds until refresh should occur.

class Client

#include <client.hpp>

The main client for interacting with Kumiho Cloud services.

The Client class provides methods for all Kumiho operations including creating and managing projects, spaces, items, revisions, artifacts, and edges.

Example:

// Create from environment variables
auto client = Client::createFromEnv();

// Create a project
auto project = client->createProject("my-project", "My VFX assets");

// Create spaces and items
auto space = client->createSpace("/" + project->getName(), "assets");
auto item = space->createItem("hero", "model");

Public Functions

explicit Client(std::shared_ptr<grpc::Channel> channel)

Construct a Client with a gRPC channel.

Parameters:

channel – The gRPC channel to use.

explicit Client(std::shared_ptr<kumiho::KumihoService::StubInterface> stub)

Construct a Client with a pre-existing stub.

Parameters:

stub – The gRPC stub to use.

std::shared_ptr<Project> createProject(const std::string &name, const std::string &description = "")

Create a new project.

Parameters:

• name – The URL-safe project name.

• description – Optional description.

Throws:

ProjectLimitError – if the project limit is reached.

Returns:

The created Project.

std::vector<std::shared_ptr<Project>> getProjects()

Get all projects.

Returns:

A list of Project objects.

std::shared_ptr<Project> getProject(const std::string &name)

Get a project by name.

Parameters:

name – The project name.

Returns:

The Project, or nullptr if not found.

void deleteProject(const std::string &project_id, bool force = false)

Delete a project.

Parameters:

• project_id – The project UUID.

• force – If true, permanently delete. If false, soft delete.

std::shared_ptr<Project> updateProject(const std::string &project_id, std::optional<bool> allow_public = std::nullopt, std::optional<std::string> description = std::nullopt)

Update a project.

Parameters:

• project_id – The project UUID.

• allow_public – Optional: set public access mode.

• description – Optional: new description.

Returns:

The updated Project.

std::shared_ptr<Space> createSpace(const std::string &parent_path, const std::string &name)

Create a new space.

Parameters:

• parent_path – The path of the parent (project or space).

• name – The space name.

Returns:

The created Space.

std::shared_ptr<Space> getSpace(const std::string &path)

Get a space by path.

Parameters:

path – The full space path.

Returns:

The Space.

std::vector<std::shared_ptr<Space>> getChildSpaces(const std::string &parent_path = "")

Get child spaces of a parent.

Parameters:

parent_path – The parent path (empty for root).

Returns:

A list of Space objects.

std::shared_ptr<Space> updateSpaceMetadata(const Kref &kref, const Metadata &metadata)

Update space metadata.

Parameters:

• kref – The space’s Kref.

• metadata – The metadata to set.

Returns:

The updated Space.

void deleteSpace(const std::string &path, bool force = false)

Delete a space.

Parameters:

• path – The space path.

• force – If true, permanently delete.

std::shared_ptr<Item> createItem(const std::string &parent_path, const std::string &name, const std::string &kind)

Create a new item.

Parameters:

• parent_path – The parent space path.

• name – The item name.

• kind – The item kind (type).

Throws:

ReservedKindError – if kind is reserved.

Returns:

The created Item.

std::shared_ptr<Item> getItem(const std::string &parent_path, const std::string &name, const std::string &kind)

Get an item by parent path, name, and kind.

Parameters:

• parent_path – The parent space path.

• name – The item name.

• kind – The item kind.

Returns:

The Item.

std::shared_ptr<Item> getItemByKref(const std::string &kref_uri)

Get an item by Kref.

Parameters:

kref_uri – The item’s Kref URI.

Returns:

The Item.

PagedList<std::shared_ptr<Item>> itemSearch(const std::string &context_filter = "", const std::string &name_filter = "", const std::string &kind_filter = "", std::optional<int32_t> page_size = std::nullopt, std::optional<std::string> cursor = std::nullopt, bool include_deprecated = false)

Search for items.

Parameters:

• context_filter – Filter by context (project/space path).

• name_filter – Filter by item name.

• kind_filter – Filter by item kind.

• page_size – Optional page size for pagination.

• cursor – Optional cursor for pagination.

• include_deprecated – Whether to include deprecated items.

Returns:

A PagedList of matching Item objects.

std::shared_ptr<Item> updateItemMetadata(const Kref &kref, const Metadata &metadata)

Update item metadata.

Parameters:

• kref – The item’s Kref.

• metadata – The metadata to set.

Returns:

The updated Item.

void deleteItem(const Kref &kref, bool force = false)

Delete an item.

Parameters:

• kref – The item’s Kref.

• force – If true, permanently delete.

void setItemDeprecated(const Kref &kref, bool deprecated)

Set item deprecated status.

Parameters:

• kref – The item’s Kref.

• deprecated – True to deprecate, false to restore.

std::shared_ptr<Revision> createRevision(const Kref &item_kref, const Metadata &metadata = {}, int number = 0)

Create a new revision.

Parameters:

• item_kref – The parent item’s Kref.

• metadata – Optional metadata.

• number – Optional specific revision number (0 for auto).

Returns:

The created Revision.

std::shared_ptr<Revision> getRevision(const std::string &kref_uri)

Get a revision by Kref.

Parameters:

kref_uri – The revision’s Kref URI.

Returns:

The Revision.

std::shared_ptr<Revision> resolveKref(const std::string &kref_uri, const std::string &tag = "", const std::string &time = "")

Resolve a Kref to a revision.

Parameters:

• kref_uri – The Kref URI.

• tag – Optional tag to resolve (e.g., “published”, “approved”).

• time – Optional time in YYYYMMDDHHMM format (e.g., “202406011330”) or ISO 8601 format (e.g., “2024-06-01T13:30:00Z”).

Returns:

The Revision, or nullptr if not found.

std::optional<std::string> resolve(const std::string &kref_uri)

Resolve a Kref to a location.

Parameters:

kref_uri – The Kref URI.

Returns:

The resolved location, or nullopt.

std::vector<std::shared_ptr<Revision>> getRevisions(const Kref &item_kref)

Get all revisions of an item.

Parameters:

item_kref – The item’s Kref.

Returns:

A list of Revision objects.

int peekNextRevision(const Kref &item_kref)

Peek at the next revision number.

Parameters:

item_kref – The item’s Kref.

Returns:

The next revision number.

std::shared_ptr<Revision> updateRevisionMetadata(const Kref &kref, const Metadata &metadata)

Update revision metadata.

Parameters:

• kref – The revision’s Kref.

• metadata – The metadata to set.

Returns:

The updated Revision.

void tagRevision(const Kref &kref, const std::string &tag)

Add a tag to a revision.

Parameters:

• kref – The revision’s Kref.

• tag – The tag to add.

void untagRevision(const Kref &kref, const std::string &tag)

Remove a tag from a revision.

Parameters:

• kref – The revision’s Kref.

• tag – The tag to remove.

bool hasTag(const Kref &kref, const std::string &tag)

Check if a revision has a tag.

Parameters:

• kref – The revision’s Kref.

• tag – The tag to check.

Returns:

True if the revision has the tag.

bool wasTagged(const Kref &kref, const std::string &tag)

Check if a revision ever had a tag.

Parameters:

• kref – The revision’s Kref.

• tag – The tag to check.

Returns:

True if the revision ever had the tag.

void setRevisionDeprecated(const Kref &kref, bool deprecated)

Set revision deprecated status.

Parameters:

• kref – The revision’s Kref.

• deprecated – True to deprecate, false to restore.

void deleteRevision(const Kref &kref, bool force = false)

Delete a revision.

Parameters:

• kref – The revision’s Kref.

• force – If true, permanently delete.

std::shared_ptr<Artifact> createArtifact(const Kref &revision_kref, const std::string &name, const std::string &location)

Create a new artifact.

Parameters:

• revision_kref – The parent revision’s Kref.

• name – The artifact name.

• location – The file path or URI.

Returns:

The created Artifact.

std::shared_ptr<Artifact> getArtifact(const Kref &revision_kref, const std::string &name)

Get an artifact by revision and name.

Parameters:

• revision_kref – The revision’s Kref.

• name – The artifact name.

Returns:

The Artifact.

std::vector<std::shared_ptr<Artifact>> getArtifacts(const Kref &revision_kref)

Get all artifacts for a revision.

Parameters:

revision_kref – The revision’s Kref.

Returns:

A list of Artifact objects.

std::vector<std::shared_ptr<Artifact>> getArtifactsByLocation(const std::string &location)

Get artifacts by location.

Parameters:

location – The file location to search.

Returns:

A list of matching Artifact objects.

void setDefaultArtifact(const Kref &revision_kref, const std::string &artifact_name)

Set the default artifact for a revision.

Parameters:

• revision_kref – The revision’s Kref.

• artifact_name – The artifact name to set as default.

std::shared_ptr<Artifact> updateArtifactMetadata(const Kref &kref, const Metadata &metadata)

Update artifact metadata.

Parameters:

• kref – The artifact’s Kref.

• metadata – The metadata to set.

Returns:

The updated Artifact.

void deleteArtifact(const Kref &kref, bool force = false)

Delete an artifact.

Parameters:

• kref – The artifact’s Kref.

• force – If true, permanently delete.

void setArtifactDeprecated(const Kref &kref, bool deprecated)

Set artifact deprecated status.

Parameters:

• kref – The artifact’s Kref.

• deprecated – True to deprecate, false to restore.

std::shared_ptr<Edge> createEdge(const Kref &source_kref, const Kref &target_kref, const std::string &edge_type, const Metadata &metadata = {})

Create an edge between revisions.

Parameters:

• source_kref – The source revision’s Kref.

• target_kref – The target revision’s Kref.

• edge_type – The edge type (e.g., “DEPENDS_ON”).

• metadata – Optional edge metadata.

Returns:

The created Edge.

std::vector<std::shared_ptr<Edge>> getEdges(const Kref &kref, const std::string &edge_type_filter = "")

Get edges for a revision.

Parameters:

• kref – The revision’s Kref.

• edge_type_filter – Filter by edge type (empty = all).

Returns:

A list of Edge objects.

void deleteEdge(const Kref &source_kref, const Kref &target_kref, const std::string &edge_type)

Delete an edge.

Parameters:

• source_kref – The source revision’s Kref.

• target_kref – The target revision’s Kref.

• edge_type – The edge type.

TraversalResult traverseEdges(const Kref &origin_kref, int direction, const std::vector<std::string> &edge_type_filter = {}, int max_depth = 10, int limit = 100, bool include_path = false)

Traverse edges from a starting revision.

Performs a breadth-first traversal of the revision graph following edges in the specified direction.

Parameters:

• origin_kref – The starting revision’s Kref.

• direction – The direction to traverse (OUTGOING or INCOMING).

• edge_type_filter – Filter by edge types (empty = all types).

• max_depth – Maximum traversal depth (default: 10, max: 20).

• limit – Maximum number of results (default: 100, max: 1000).

• include_path – Whether to include full path info.

Returns:

TraversalResult containing discovered revisions.

ShortestPathResult findShortestPath(const Kref &source_kref, const Kref &target_kref, const std::vector<std::string> &edge_type_filter = {}, int max_depth = 10, bool all_shortest = false)

Find the shortest path between two revisions.

Uses graph traversal to find how two revisions are connected.

Parameters:

• source_kref – The source revision’s Kref.

• target_kref – The target revision’s Kref.

• edge_type_filter – Filter by edge types (empty = all).

• max_depth – Maximum path length to search (default: 10).

• all_shortest – If true, return all shortest paths.

Returns:

ShortestPathResult containing the path(s).

ImpactAnalysisResult analyzeImpact(const Kref &revision_kref, const std::vector<std::string> &edge_type_filter = {}, int max_depth = 10, int limit = 100)

Analyze the impact of changes to a revision.

Returns all revisions that directly or indirectly depend on the specified revision, sorted by impact depth.

Parameters:

• revision_kref – The revision to analyze.

• edge_type_filter – Edge types to follow (empty = all).

• max_depth – Maximum traversal depth (default: 10).

• limit – Maximum results (default: 100).

Returns:

ImpactAnalysisResult with impacted revisions.

std::optional<std::string> getAttribute(const Kref &kref, const std::string &key)

Get a single metadata attribute.

Retrieves a specific attribute value from any entity (product, version, resource, group).

Parameters:

• kref – The entity’s Kref.

• key – The attribute key to retrieve.

Returns:

The attribute value, or nullopt if not found.

bool setAttribute(const Kref &kref, const std::string &key, const std::string &value)

Set a single metadata attribute.

Creates or updates a specific attribute on any entity. This is more efficient than setMetadata when updating a single value.

Parameters:

• kref – The entity’s Kref.

• key – The attribute key to set.

• value – The attribute value.

Returns:

True if the attribute was set successfully.

bool deleteAttribute(const Kref &kref, const std::string &key)

Delete a single metadata attribute.

Removes a specific attribute from any entity.

Parameters:

• kref – The entity’s Kref.

• key – The attribute key to delete.

Returns:

True if the attribute was deleted successfully.

std::shared_ptr<Bundle> createBundle(const std::string &parent_path, const std::string &name)

Create a bundle.

Parameters:

• parent_path – The parent space path.

• name – The bundle name.

Returns:

The created Bundle.

std::shared_ptr<Bundle> createBundle(const Kref &parent_kref, const std::string &name)

Create a bundle using a parent Kref.

Parameters:

• parent_kref – The parent’s Kref.

• name – The bundle name.

Returns:

The created Bundle.

std::shared_ptr<Bundle> getBundle(const std::string &parent_path, const std::string &name)

Get a bundle by parent path and name.

Parameters:

• parent_path – The parent space path.

• name – The bundle name.

Returns:

The Bundle.

void addBundleMember(const Kref &bundle_kref, const Kref &item_kref)

Add a member to a bundle.

Parameters:

• bundle_kref – The bundle’s Kref.

• item_kref – The item to add.

void removeBundleMember(const Kref &bundle_kref, const Kref &item_kref)

Remove a member from a bundle.

Parameters:

• bundle_kref – The bundle’s Kref.

• item_kref – The item to remove.

std::vector<BundleMember> getBundleMembers(const Kref &bundle_kref)

Get bundle members.

Parameters:

bundle_kref – The bundle’s Kref.

Returns:

A list of BundleMember objects.

std::vector<BundleRevisionHistory> getBundleHistory(const Kref &bundle_kref)

Get bundle history.

Parameters:

bundle_kref – The bundle’s Kref.

Returns:

A list of BundleRevisionHistory objects.

TenantUsage getTenantUsage()

Get the current tenant’s usage and limits.

Returns information about the tenant’s resource consumption and quota limits.

Returns:

A TenantUsage struct with node_count, node_limit, and tenant_id.

std::shared_ptr<EventStream> eventStream(const std::string &routing_key_filter = "", const std::string &kref_filter = "")

Subscribe to event stream.

Parameters:

• routing_key_filter – Filter by routing key pattern.

• kref_filter – Filter by Kref pattern.

Returns:

An EventStream for receiving events.

void setAuthToken(const std::string &token)

Set the authentication token for gRPC calls.

Parameters:

token – The bearer token to use for authorization.

inline const std::string &getAuthToken() const

Get the current authentication token.

Returns:

The current token, or empty string if not set.

inline kumiho::KumihoService::StubInterface *getStub()

Get the raw gRPC stub.

Returns:

Pointer to the stub interface.

Public Static Functions

static std::shared_ptr<Client> createFromEnv()

Create a Client from environment variables.

Resolves the server endpoint using:

1. KUMIHO_SERVER_ENDPOINT (preferred)

2. KUMIHO_SERVER_ADDRESS (legacy)

3. localhost:50051 (default)

Returns:

A shared pointer to the created Client.

Private Functions

void configureContext(grpc::ClientContext &context) const

Configure a ClientContext with authentication metadata.

Parameters:

context – The context to configure.

Private Members

std::shared_ptr<kumiho::KumihoService::StubInterface> stub_

std::shared_ptr<grpc::ClientContext> context_

std::string auth_token_

class DiscoveryCache

#include <discovery.hpp>

Encrypted JSON file cache for discovery records.

Stores discovery records in an encrypted JSON file, keyed by tenant hint. The default location is ~/.kumiho/discovery-cache.json.

Cache data is encrypted at rest using a machine-specific key derived from hardware identifiers, providing defense-in-depth protection for tenant metadata.

Public Functions

explicit DiscoveryCache(const std::filesystem::path &path = {}, bool encrypt = true)

Construct a cache with the default or specified path.

Parameters:

• path – Optional path to the cache file.

• encrypt – Whether to encrypt cache data (default: true).

std::optional<DiscoveryRecord> load(const std::string &cache_key)

Load a cached discovery record.

Parameters:

cache_key – The cache key (tenant hint or “__default__”).

Returns:

The cached record, or nullopt if not found or invalid.

void store(const std::string &cache_key, const DiscoveryRecord &record)

Store a discovery record in the cache.

Parameters:

• cache_key – The cache key.

• record – The record to store.

inline const std::filesystem::path &getPath() const

Get the cache file path.

Returns:

The filesystem path to the cache file.

Private Functions

std::map<std::string, std::map<std::string, std::string>> readAll()

std::string encryptContent(const std::string &plaintext)

Encrypt cache content for storage.

Parameters:

plaintext – The JSON content to encrypt.

Returns:

The encrypted content with “enc:v1:” prefix.

std::string decryptContent(const std::string &encrypted)

Decrypt cache content from storage.

Parameters:

encrypted – The encrypted content.

Returns:

The decrypted JSON, or empty string if decryption fails.

std::vector<uint8_t> deriveKey()

Get machine-specific encryption key.

Returns:

32-byte key derived from machine ID.

Private Members

std::filesystem::path path_

bool encrypt_

class DiscoveryError : public kumiho::api::KumihoError

#include <error.hpp>

Exception for discovery failures.

Thrown when the discovery endpoint cannot be reached or returns an unexpected response.

Public Functions

inline explicit DiscoveryError(const std::string &message)

class DiscoveryManager

#include <discovery.hpp>

Manager for discovery endpoint interactions.

Coordinates cache usage and remote discovery calls to the control plane.

Public Functions

explicit DiscoveryManager(const std::string &control_plane_url = "", const std::filesystem::path &cache_path = {}, double timeout_seconds = 10.0)

Construct a discovery manager.

Parameters:

• control_plane_url – The control plane base URL (default: https://control.kumiho.cloud).

• cache_path – Optional path to the cache file.

• timeout_seconds – Request timeout in seconds (default: 10).

DiscoveryRecord resolve(const std::string &id_token, const std::optional<std::string> &tenant_hint = std::nullopt, bool force_refresh = false)

Resolve tenant routing via discovery.

Uses the cache when available and valid, or fetches fresh data from the control plane discovery endpoint.

Parameters:

• id_token – The Firebase ID token for authentication.

• tenant_hint – Optional tenant ID hint for multi-tenant users.

• force_refresh – Force a fresh fetch even if cache is valid.

Throws:

DiscoveryError – if the endpoint cannot be reached.

Returns:

The resolved discovery record.

Private Functions

DiscoveryRecord fetchRemote(const std::string &id_token, const std::optional<std::string> &tenant_hint)

Private Members

std::string base_url_

DiscoveryCache cache_

double timeout_

struct DiscoveryRecord

#include <discovery.hpp>

A complete discovery record from the control plane.

Contains tenant information, role assignments, region routing, and cache control metadata.

Public Members

std::string tenant_id

The tenant’s unique identifier.

std::optional<std::string> tenant_name

The tenant’s display name (optional).

std::vector<std::string> roles

List of role assignments for the user.

std::optional<std::map<std::string, std::string>> guardrails

Optional guardrails/limits for the tenant.

RegionRouting region

Region routing information.

CacheControl cache_control

Cache control metadata.

class Edge

#include <edge.hpp>

A relationship between two revisions in the Kumiho system.

Edges represent semantic relationships between revisions, enabling dependency tracking, lineage visualization, and impact analysis. They are directional (source -> target) and typed.

Common use cases:

• Track which textures a model uses (DEPENDS_ON)

• Record that a LOD was created from a high-poly model (DERIVED_FROM)

• Link a render to the scene file that created it (CREATED_FROM)

Example:

auto edges = revision->getEdges(EdgeType::DEPENDS_ON);
for (const auto& edge : edges) {
    std::cout << edge->getSourceKref().uri() 
              << " depends on " 
              << edge->getTargetKref().uri() << std::endl;
}

Public Functions

Edge(const ::kumiho::Edge &edge, Client *client)

Construct an Edge from a protobuf message.

Parameters:

• edge – The protobuf Edge message.

• client – The client for making API calls.

Kref getSourceKref() const

Get the source revision’s Kref.

Returns:

The Kref of the source revision.

Kref getTargetKref() const

Get the target revision’s Kref.

Returns:

The Kref of the target revision.

std::string getEdgeType() const

Get the edge type.

Returns:

The edge type string (e.g., “DEPENDS_ON”).

Metadata getMetadata() const

Get the edge’s metadata.

Returns:

A map of metadata key-value pairs.

std::optional<std::string> getCreatedAt() const

Get the creation timestamp.

Returns:

ISO timestamp when the edge was created, or empty.

std::string getAuthor() const

Get the author’s user ID.

Returns:

The UUID of the user who created the edge.

std::string getUsername() const

Get the author’s display name.

Returns:

The username of the edge creator.

void deleteEdge()

Delete this edge.

Private Members

::kumiho::Edge edge_

Client *client_

struct EdgeType

#include <edge.hpp>

Standard edge types for Kumiho relationships.

These constants define the semantic meaning of relationships between revisions. All edge types use UPPERCASE format as required by the Neo4j graph database.

Example:

revision->createEdge(texture, EdgeType::DEPENDS_ON);

Public Static Attributes

static constexpr const char *BELONGS_TO = "BELONGS_TO"

Indicates ownership or grouping relationship.

static constexpr const char *CREATED_FROM = "CREATED_FROM"

Indicates the source was generated/created from target.

static constexpr const char *REFERENCED = "REFERENCED"

Indicates a soft reference relationship.

static constexpr const char *DEPENDS_ON = "DEPENDS_ON"

Indicates the source requires target to function.

static constexpr const char *DERIVED_FROM = "DERIVED_FROM"

Indicates the source was derived or modified from target.

static constexpr const char *CONTAINS = "CONTAINS"

Indicates the source contains or includes target.

class EdgeTypeValidationError : public kumiho::api::ValidationError

#include <error.hpp>

Exception for edge type validation failures.

Thrown when an edge type does not match the required format (uppercase, alphanumeric with underscores, 1-50 chars).

Public Functions

inline explicit EdgeTypeValidationError(const std::string &message)

class Event

#include <event.hpp>

A real-time event from the Kumiho server.

Events are emitted when entities are created, updated, or deleted. Each event has a routing key for filtering and details about what changed.

Example:

auto stream = client->eventStream("product.*");
Event event;
while (stream->readNext(event)) {
    std::cout << "Event: " << event.getRoutingKey() << std::endl;
    std::cout << "Kref: " << event.getKref().uri() << std::endl;
}

Public Functions

Event(const ::kumiho::Event &event = ::kumiho::Event())

Construct an Event from a protobuf message.

Parameters:

event – The protobuf Event message (default: empty).

std::string getRoutingKey() const

Get the routing key for this event.

Routing keys follow the format: entity.action (e.g., “version.created”).

Returns:

The routing key string.

Kref getKref() const

Get the Kref of the affected entity.

Returns:

The Kref of the entity that triggered the event.

Metadata getDetails() const

Get additional event details.

Returns:

A map of detail key-value pairs.

Private Members

::kumiho::Event event_

class EventStream

#include <event.hpp>

A streaming connection for receiving events.

EventStream wraps a gRPC client reader for receiving a continuous stream of events from the server. Use readNext() to block and wait for the next event.

Example:

auto stream = client->eventStream();
Event event;
while (stream->readNext(event)) {
    // Process event
}
// Stream ended or error occurred

Public Functions

EventStream(std::unique_ptr<grpc::ClientReaderInterface<::kumiho::Event>> reader)

Construct an EventStream from a gRPC reader.

Parameters:

reader – The gRPC client reader for events.

bool readNext(Event &event)

Read the next event from the stream.

Blocks until an event is available or the stream ends.

Parameters:

event – [out] The event to populate.

Returns:

True if an event was read, false if the stream ended.

Private Members

std::unique_ptr<grpc::ClientReaderInterface<::kumiho::Event>> reader_

struct ImpactAnalysisResult

#include <types.hpp>

Result of an impact analysis operation.

Contains all revisions that would be affected by changes to a source revision.

Public Members

std::vector<ImpactedRevision> impacted_revisions

All revisions that would be impacted.

int total_impacted = 0

Total number of impacted revisions.

bool truncated = false

True if results were limited/truncated.

struct ImpactedRevision

#include <types.hpp>

A revision that would be impacted by changes.

Used in impact analysis to identify downstream dependencies.

Public Members

std::string revision_kref

The impacted revision’s Kref.

std::string item_kref

The item’s Kref.

int impact_depth

How many hops away from the source.

std::vector<std::string> impact_path_types

Edge types in the impact chain.

class Item

#include <item.hpp>

A versioned asset in the Kumiho system.

Items represent assets that can have multiple revisions. Each item belongs to a space and is identified by a combination of name and kind.

The item’s kref (Kumiho Reference) is a URI that uniquely identifies it: kref://project/space/item.kind

Example:

auto item = space->createItem("hero", "model");

// Create revisions
auto v1 = item->createRevision();
auto v2 = item->createRevision({{"notes", "Updated mesh"}});

// Get specific revision
auto v1 = item->getRevision(1);
auto latest = item->getLatestRevision();

// Get revision by tag
auto approved = item->getRevisionByTag("approved");

Public Functions

Item(const ::kumiho::ItemResponse &response, Client *client)

Construct an Item from a protobuf response.

Parameters:

• response – The protobuf ItemResponse message.

• client – The client for making API calls.

Kref getKref() const

Get the item’s unique Kref.

Returns:

The Kref URI for this item.

std::string getName() const

Get the full name including kind.

Returns:

The full item name (e.g., “hero.model”).

std::string getItemName() const

Get the base item name.

Returns:

The item name without kind (e.g., “hero”).

std::string getKind() const

Get the item kind.

Returns:

The item kind (e.g., “model”, “texture”).

Metadata getMetadata() const

Get the item’s metadata.

Returns:

A map of metadata key-value pairs.

std::optional<std::string> getCreatedAt() const

Get the creation timestamp.

Returns:

ISO timestamp when the item was created, or nullopt.

std::string getAuthor() const

Get the author’s user ID.

Returns:

The UUID of the user who created the item.

std::string getUsername() const

Get the author’s display name.

Returns:

The username of the item creator.

bool isDeprecated() const

Check if the item is deprecated.

Returns:

True if deprecated, false otherwise.

std::shared_ptr<Revision> createRevision(const Metadata &metadata = {})

Create a new revision of this item.

Revisions are automatically numbered sequentially. Each revision starts with the “latest” tag, which moves to the newest revision.

Parameters:

metadata – Optional metadata for the revision.

Returns:

The created Revision.

std::shared_ptr<Revision> getRevision(int revision_number)

Get a specific revision by number.

Parameters:

revision_number – The revision number (1-based).

Returns:

The Revision.

std::vector<std::shared_ptr<Revision>> getRevisions()

Get all revisions of this item.

Returns:

A list of Revision objects, ordered by revision number.

std::shared_ptr<Revision> getRevisionByTag(const std::string &tag)

Get a revision by tag.

Parameters:

tag – The tag to search for.

Returns:

The Revision, or nullptr if not found.

std::shared_ptr<Revision> getRevisionByTime(const std::string &time)

Get a revision by creation time.

Parameters:

time – The time in one of these formats:

• YYYYMMDDHHMM (e.g., “202406011330”)

• ISO 8601 (e.g., “2024-06-01T13:30:00Z”)

Returns:

The Revision, or nullptr if not found.

std::shared_ptr<Revision> getRevisionByTime(std::chrono::system_clock::time_point time_point)

Get a revision by creation time using std::chrono.

Parameters:

time_point – The time as a std::chrono::system_clock::time_point.

Returns:

The Revision, or nullptr if not found.

std::shared_ptr<Revision> getRevisionByTagAndTime(const std::string &tag, const std::string &time)

Get a revision by both tag and time.

This finds the revision that had the specified tag at the specified time. Useful for reconstructing historical states and reproducible builds.

Example:

// Get the "published" revision as of June 1st, 2024
auto rev = item->getRevisionByTagAndTime("published", "202406010000");

// Using ISO 8601 format
auto rev = item->getRevisionByTagAndTime("published", "2024-06-01T00:00:00Z");

Parameters:

• tag – The tag to search for (e.g., “published”, “approved”).

• time – The time in YYYYMMDDHHMM or ISO 8601 format.

Returns:

The Revision, or nullptr if not found.

std::shared_ptr<Revision> getRevisionByTagAndTime(const std::string &tag, std::chrono::system_clock::time_point time_point)

Get a revision by both tag and time using std::chrono.

Parameters:

• tag – The tag to search for.

• time_point – The time as a std::chrono::system_clock::time_point.

Returns:

The Revision, or nullptr if not found.

std::shared_ptr<Revision> getLatestRevision()

Get the latest revision.

Returns:

The latest Revision, or nullptr if no revisions exist.

int peekNextRevision()

Peek at the next revision number.

Returns:

The next revision number that would be assigned.

std::shared_ptr<Item> setMetadata(const Metadata &metadata)

Set or update metadata for this item.

Parameters:

metadata – Dictionary of metadata key-value pairs.

Returns:

The updated Item.

std::optional<std::string> getAttribute(const std::string &key)

Get a single metadata attribute.

Parameters:

key – The attribute key to retrieve.

Returns:

The attribute value, or nullopt if not found.

bool setAttribute(const std::string &key, const std::string &value)

Set a single metadata attribute.

Parameters:

• key – The attribute key to set.

• value – The attribute value.

Returns:

True if the attribute was set successfully.

bool deleteAttribute(const std::string &key)

Delete a single metadata attribute.

Parameters:

key – The attribute key to delete.

Returns:

True if the attribute was deleted successfully.

void deleteItem(bool force = false)

Delete this item.

Parameters:

force – If true, permanently delete. If false, soft delete.

std::shared_ptr<Space> getSpace()

Get the parent space.

Returns:

The Space containing this item.

std::shared_ptr<Project> getProject()

Get the parent project.

Returns:

The Project containing this item.

void setDeprecated(bool deprecated)

Set the deprecated status.

Parameters:

deprecated – True to deprecate, false to restore.

std::shared_ptr<Item> refresh()

Refresh this item’s data from the server.

Returns:

The refreshed Item.

Private Members

::kumiho::ItemResponse response_

Client *client_

class Kref : public std::string

#include <kref.hpp>

A Kumiho Reference URI that uniquely identifies any object.

Kref URIs follow the format:

• Project: kref://project-name

• Space: kref://project/space/subspace

• Item: kref://project/space/item.kind

• Revision: kref://project/space/item.kind?r=1

• Artifact: kref://project/space/item.kind?r=1&a=artifact

Legacy format with kumiho:// prefix is also supported.

Example:

Kref kref("kref://my-project/assets/hero.model?r=1");
std::cout << kref.getProject();   // "my-project"
std::cout << kref.getSpace();     // "assets"
std::cout << kref.getItemName();  // "hero"
std::cout << kref.getKind();      // "model"
std::cout << kref.getRevision();  // 1

Public Functions

explicit Kref(const std::string &uri = "")

Construct a Kref from a URI string.

Parameters:

uri – The Kref URI string.

inline const std::string &uri() const

Get the full URI string.

Returns:

The complete Kref URI.

std::string getPath() const

Get the path component (everything after scheme, before query).

Returns:

The path portion of the URI.

std::string getProject() const

Get the project name (first path component).

Returns:

The project name.

std::string getSpace() const

Get the space path (path between project and item).

Returns:

The space path, or empty if this is a project-level kref.

inline std::string getGroup() const

std::string getItemName() const

Get the base item name (without kind).

Returns:

The item name, or empty if this is a space-level kref.

inline std::string getProductName() const

std::string getKind() const

Get the item kind.

Returns:

The item kind (e.g., “model”, “texture”), or empty.

inline std::string getType() const

std::string getFullItemName() const

Get the full item name including kind.

Returns:

The full item name (e.g., “hero.model”), or empty.

inline std::string getFullProductName() const

std::optional<int> getRevision() const

Get the revision number if present.

Returns:

The revision number, or std::nullopt if not specified.

inline std::optional<int> getVersion() const

std::string getArtifactName() const

Get the artifact name if present.

Returns:

The artifact name, or empty if not specified.

inline std::string getResourceName() const

std::string getTag() const

Get the tag query parameter if present.

Returns:

The tag value, or empty if not specified.

std::string getTime() const

Get the time query parameter if present.

Returns:

The time value, or empty if not specified.

::kumiho::Kref toPb() const

Convert to protobuf Kref message.

Returns:

A protobuf Kref with this URI.

bool isValid() const

Check if this is a valid Kref.

Returns:

True if the URI is non-empty and has valid format.

inline bool operator==(const Kref &other) const

Equality comparison with another Kref.

inline bool operator==(const std::string &other) const

Equality comparison with a string.

Private Functions

std::string getQueryParam(const std::string &param) const

Extract a query parameter value.

Parameters:

param – The parameter name (e.g., “v”, “r”, “t”).

Returns:

The parameter value, or empty if not found.

class KrefValidationError : public kumiho::api::ValidationError

#include <error.hpp>

Exception for Kref URI validation failures.

Thrown when a Kref string does not match the expected format.

Public Functions

inline explicit KrefValidationError(const std::string &message)

class KumihoError : public std::runtime_error

#include <error.hpp>

Base exception for all Kumiho errors.

All Kumiho-specific exceptions inherit from this class, allowing catch blocks to handle all Kumiho errors uniformly.

Subclassed by kumiho::api::AuthenticationError, kumiho::api::DiscoveryError, kumiho::api::NotFoundError, kumiho::api::ProjectLimitError, kumiho::api::RpcError, kumiho::api::ValidationError

Public Functions

inline explicit KumihoError(const std::string &message)

class NotFoundError : public kumiho::api::KumihoError

#include <error.hpp>

Exception for NOT_FOUND errors.

Thrown when a requested entity (group, product, version, etc.) does not exist.

Public Functions

inline explicit NotFoundError(const std::string &message)

template<typename T>
struct PagedList

#include <types.hpp>

A list that also contains pagination information.

Template Parameters:

T – The type of items in the list.

Public Members

std::vector<T> items

std::optional<std::string> next_cursor

std::optional<int32_t> total_count

struct PathStep

#include <types.hpp>

A single step in a graph traversal path.

Represents one hop in a path between revisions, including the revision reached and the relationship type used.

Public Members

std::string revision_kref

The revision’s Kref at this step.

std::string edge_type

The edge type used to reach this node (e.g., “DEPENDS_ON”).

int depth

Distance from the origin (0 = origin).

class Project

#include <project.hpp>

A Kumiho project—the top-level container for assets.

Projects are the root of the Kumiho hierarchy. Each project has its own namespace for spaces and items, and manages access control and settings independently.

Projects support both public and private access modes, allowing you to share assets publicly or restrict them to authenticated users.

Example:

auto project = client->createProject("film-2024", "Feature film VFX assets");

// Create space structure
auto chars = project->createSpace("characters");
auto envs = project->createSpace("environments");

// List all spaces recursively
for (const auto& space : project->getSpaces(true)) {
    std::cout << space->getPath() << std::endl;
}

// Enable public access
project->setPublic(true);

Public Functions

Project(const ::kumiho::ProjectResponse &response, Client *client)

Construct a Project from a protobuf response.

Parameters:

• response – The protobuf ProjectResponse message.

• client – The client for making API calls.

std::string getProjectId() const

Get the project’s unique ID.

Returns:

The project UUID.

std::string getName() const

Get the project’s URL-safe name.

Returns:

The project name (e.g., “film-2024”).

Kref getKref() const

Get the project’s Kref.

Returns:

A Kref for this project.

std::string getDescription() const

Get the project’s description.

Returns:

The human-readable description.

std::optional<std::string> getCreatedAt() const

Get the creation timestamp.

Returns:

ISO timestamp when the project was created, or nullopt.

std::optional<std::string> getUpdatedAt() const

Get the last update timestamp.

Returns:

ISO timestamp of the last update, or nullopt.

bool isDeprecated() const

Check if the project is deprecated.

Returns:

True if deprecated (soft-deleted), false otherwise.

bool isPublic() const

Check if public access is allowed.

Returns:

True if anonymous read access is enabled.

std::shared_ptr<Space> createSpace(const std::string &name)

Create a space in this project.

Parameters:

name – The space name.

Returns:

The created Space.

std::shared_ptr<Space> getSpace(const std::string &path)

Get a space by path.

Parameters:

path – The space path relative to the project (e.g., “assets/models”).

Returns:

The Space.

std::vector<std::shared_ptr<Space>> getSpaces(bool recursive = false)

Get all spaces in this project.

Parameters:

recursive – If true, include all descendant spaces.

Returns:

A list of Space objects.

PagedList<std::shared_ptr<Item>> getItems(const std::string &name_filter = "", const std::string &kind_filter = "", std::optional<int32_t> page_size = std::nullopt, std::optional<std::string> cursor = std::nullopt)

Search for items within this project.

Parameters:

• name_filter – Filter by item name. Supports wildcards.

• kind_filter – Filter by item kind.

• page_size – Optional page size for pagination.

• cursor – Optional cursor for pagination.

Returns:

A PagedList of Item objects.

std::shared_ptr<Bundle> createBundle(const std::string &name)

Create a bundle in this project.

Parameters:

name – The bundle name.

Returns:

The created Bundle.

std::shared_ptr<Bundle> getBundle(const std::string &name)

Get a bundle by name.

Parameters:

name – The bundle name.

Returns:

The Bundle.

std::shared_ptr<Project> setPublic(bool allow)

Set public access mode.

Parameters:

allow – True to enable public access, false to restrict.

Returns:

The updated Project.

std::shared_ptr<Project> setAllowPublic(bool allow_public)

Alias for setPublic() using the allow_public terminology.

Parameters:

allow_public – True to enable public access, false to restrict.

Returns:

The updated Project.

std::shared_ptr<Project> update(const std::string &description)

Update the project’s description.

Parameters:

description – The new description.

Returns:

The updated Project.

void deleteProject(bool force = false)

Delete this project.

Parameters:

force – If true, permanently delete. If false, soft delete (deprecate).

Private Members

::kumiho::ProjectResponse response_

Client *client_

class ProjectLimitError : public kumiho::api::KumihoError

#include <error.hpp>

Exception for project limit exceeded.

Thrown when attempting to create a project but the tenant’s project limit has been reached (RESOURCE_EXHAUSTED).

Public Functions

inline explicit ProjectLimitError(const std::string &message)

struct RegionRouting

#include <discovery.hpp>

Region routing information from discovery.

Contains the endpoint and optional gRPC authority override for a region.

Public Members

std::string region_code

The region code (e.g., “us-central1”, “asia-northeast3”).

std::string server_url

The gRPC server URL (e.g., “grpc.kumiho.io:443”).

std::optional<std::string> grpc_authority

Optional gRPC authority override for TLS verification.

class ReservedKindError : public kumiho::api::ValidationError

#include <error.hpp>

Exception for reserved kind violations.

Thrown when attempting to create an item with a reserved kind (e.g., “bundle”) using createItem() instead of the dedicated method.

Public Functions

inline explicit ReservedKindError(const std::string &message)

class Revision

#include <revision.hpp>

A specific iteration of an item in the Kumiho system.

Revisions are snapshots of an item at a point in time. Each revision can have multiple artifacts (file references), tags for categorization, and edges to other revisions for dependency tracking.

The revision’s kref includes the revision number: kref://project/space/item.kind?r=1

Example:

auto v1 = item->createRevision({{"artist", "jane"}});

// Add artifacts
auto mesh = v1->createArtifact("mesh", "/assets/hero.fbx");
auto rig = v1->createArtifact("rig", "/assets/hero_rig.fbx");

// Set default artifact
v1->setDefaultArtifact("mesh");

// Tag the revision
v1->tag("approved");

// Check tags
if (v1->hasTag("approved")) {
    std::cout << "Revision is approved!" << std::endl;
}

Public Functions

Revision(const ::kumiho::RevisionResponse &response, Client *client)

Construct a Revision from a protobuf response.

Parameters:

• response – The protobuf RevisionResponse message.

• client – The client for making API calls.

Kref getKref() const

Get the revision’s unique Kref.

Returns:

The Kref URI for this revision.

Kref getItemKref() const

Get the parent item’s Kref.

Returns:

The Kref of the item containing this revision.

int getRevisionNumber() const

Get the revision number.

Returns:

The revision number (1-based).

std::vector<std::string> getTags() const

Get the tags applied to this revision.

Returns:

A list of tag strings.

Metadata getMetadata() const

Get the revision’s metadata.

Returns:

A map of metadata key-value pairs.

std::optional<std::string> getCreatedAt() const

Get the creation timestamp.

Returns:

ISO timestamp when the revision was created, or nullopt.

std::string getAuthor() const

Get the author’s user ID.

Returns:

The UUID of the user who created the revision.

std::string getUsername() const

Get the author’s display name.

Returns:

The username of the revision creator.

bool isLatest() const

Check if this is the latest revision.

Returns:

True if this is the latest revision of the item.

bool isDeprecated() const

Check if the revision is deprecated.

Returns:

True if deprecated, false otherwise.

bool isPublished() const

Check if the revision is published.

Published revisions are immutable—their metadata cannot be changed.

Returns:

True if published, false otherwise.

std::optional<std::string> getDefaultArtifact() const

Get the default artifact name.

Returns:

The name of the default artifact, or nullopt if not set.

void setDefaultArtifact(const std::string &artifact_name)

Set the default artifact for this revision.

Parameters:

artifact_name – The name of the artifact to set as default.

std::shared_ptr<Artifact> createArtifact(const std::string &name, const std::string &location)

Create a new artifact for this revision.

Artifacts are file references that point to actual assets on disk or network storage. Kumiho tracks the path and metadata but does not upload or copy the files.

Parameters:

• name – The name of the artifact (e.g., “mesh”, “textures”).

• location – The file path or URI where the artifact is stored.

Returns:

The created Artifact.

std::shared_ptr<Artifact> getArtifact(const std::string &name)

Get an artifact by name.

Parameters:

name – The artifact name.

Returns:

The Artifact.

std::vector<std::shared_ptr<Artifact>> getArtifacts()

Get all artifacts for this revision.

Returns:

A list of Artifact objects.

std::vector<std::string> getLocations()

Get all artifact locations.

Returns:

A list of location strings.

std::shared_ptr<Revision> setMetadata(const Metadata &metadata)

Set or update metadata for this revision.

Parameters:

metadata – Dictionary of metadata key-value pairs.

Returns:

The updated Revision.

std::optional<std::string> getAttribute(const std::string &key)

Get a single metadata attribute.

Parameters:

key – The attribute key to retrieve.

Returns:

The attribute value, or nullopt if not found.

bool setAttribute(const std::string &key, const std::string &value)

Set a single metadata attribute.

Parameters:

• key – The attribute key to set.

• value – The attribute value.

Returns:

True if the attribute was set successfully.

bool deleteAttribute(const std::string &key)

Delete a single metadata attribute.

Parameters:

key – The attribute key to delete.

Returns:

True if the attribute was deleted successfully.

void tag(const std::string &tag)

Add a tag to this revision.

Tags are used to categorize revisions and mark their status. Common user tags include “published”, “approved”, etc.

Note: “latest” is a reserved system tag managed by the server and cannot be set or removed manually.

The server records the timestamp when a tag is applied, enabling time-based queries like “what was published on June 1st?” Use Item::getRevisionByTagAndTime() for historical tag lookups.

Example:

revision->tag("approved");
revision->tag("published");

Parameters:

tag – The tag to add.

void untag(const std::string &tag)

Remove a tag from this revision.

The server records when the tag was removed, preserving the history. Use wasTagged() to check if a tag was ever applied, even after removal.

Parameters:

tag – The tag to remove.

bool hasTag(const std::string &tag)

Check if this revision currently has a tag.

Parameters:

tag – The tag to check.

Returns:

True if the revision currently has the tag.

bool wasTagged(const std::string &tag)

Check if this revision ever had a tag (including removed tags).

This checks the historical record. A tag that was applied and later removed will still return true. Use this for auditing.

Parameters:

tag – The tag to check.

Returns:

True if the revision ever had the tag.

void deleteRevision(bool force = false)

Delete this revision.

Parameters:

force – If true, permanently delete. If false, soft delete.

std::shared_ptr<Item> getItem()

Get the parent item.

Returns:

The Item containing this revision.

std::shared_ptr<Space> getSpace()

Get the parent space.

Returns:

The Space containing this revision’s item.

std::shared_ptr<Project> getProject()

Get the parent project.

Returns:

The Project containing this revision.

std::shared_ptr<Edge> createEdge(const Kref &target, const std::string &edge_type, const Metadata &metadata = {})

Create an edge from this revision to another.

Parameters:

• target – The target revision’s Kref.

• edge_type – The type of relationship (e.g., EdgeType::DEPENDS_ON).

• metadata – Optional metadata for the edge.

Returns:

The created Edge.

std::vector<std::shared_ptr<Edge>> getEdges(const std::string &edge_type_filter = "", EdgeDirection direction = EdgeDirection::OUTGOING)

Get edges from or to this revision.

Parameters:

• edge_type_filter – Filter by edge type (empty = all types).

• direction – The direction to query (default: OUTGOING).

Returns:

A list of Edge objects.

std::shared_ptr<Revision> refresh()

Refresh this revision’s data from the server.

Returns:

The refreshed Revision.

void setDeprecated(bool deprecated)

Set the deprecated status.

Parameters:

deprecated – True to deprecate, false to restore.

std::shared_ptr<Revision> publish()

Publish this revision (adds published tag, makes immutable).

Returns:

The updated Revision.

TraversalResult getAllDependencies(const std::vector<std::string> &edge_type_filter = {}, int max_depth = 10, int limit = 100)

Get all transitive dependencies of this revision.

Traverses outgoing edges to find all revisions this revision depends on, directly or indirectly.

Example:

auto deps = revision->getAllDependencies({"DEPENDS_ON"}, 5);
for (const auto& kref : deps.revision_krefs) {
    std::cout << "Depends on: " << kref << std::endl;
}

Parameters:

• edge_type_filter – Filter by edge types (empty = all).

• max_depth – Maximum traversal depth (default: 10).

• limit – Maximum number of results (default: 100).

Returns:

TraversalResult containing discovered revisions.

TraversalResult getAllDependents(const std::vector<std::string> &edge_type_filter = {}, int max_depth = 10, int limit = 100)

Get all revisions that transitively depend on this revision.

Traverses incoming edges to find all revisions that depend on this revision, directly or indirectly. Useful for impact analysis.

Parameters:

• edge_type_filter – Filter by edge types.

• max_depth – Maximum traversal depth.

• limit – Maximum number of results.

Returns:

TraversalResult containing dependent revisions.

ShortestPathResult findPathTo(const Kref &target, const std::vector<std::string> &edge_type_filter = {}, int max_depth = 10, bool all_paths = false)

Find the shortest path from this revision to another.

Uses graph traversal to find how two revisions are connected.

Example:

auto result = model->findPathTo(texture->getKref());
if (result.path_exists) {
    std::cout << "Path length: " << result.path_length << std::endl;
}

Parameters:

• target – The target revision’s Kref.

• edge_type_filter – Filter by edge types.

• max_depth – Maximum path length to search.

• all_paths – If true, returns all shortest paths.

Returns:

ShortestPathResult containing the path(s).

ImpactAnalysisResult analyzeImpact(const std::vector<std::string> &edge_type_filter = {}, int max_depth = 10, int limit = 100)

Analyze the impact of changes to this revision.

Returns all revisions that directly or indirectly depend on this revision, sorted by impact depth (closest dependencies first).

Example:

auto impact = texture->analyzeImpact({"DEPENDS_ON"});
std::cout << impact.total_impacted << " revisions affected" << std::endl;

Parameters:

• edge_type_filter – Edge types to follow (empty = all).

• max_depth – Maximum traversal depth (default: 10).

• limit – Maximum results (default: 100).

Returns:

ImpactAnalysisResult with impacted revisions.

Private Members

::kumiho::RevisionResponse response_

Client *client_

struct RevisionPath

#include <types.hpp>

A complete path between two revisions.

Contains the sequence of steps from a source to a target revision.

Public Functions

inline bool empty() const

Check if the path is empty.

Public Members

std::vector<PathStep> steps

The sequence of steps in the path.

int total_depth = 0

Total depth/length of the path.

class RpcError : public kumiho::api::KumihoError

#include <error.hpp>

Exception for gRPC communication failures.

Thrown when an RPC call fails due to network issues, server errors, or other gRPC-level problems.

Public Functions

inline explicit RpcError(const std::string &message, int code = 0)

inline int code() const noexcept

Get the gRPC status code.

Returns:

The gRPC status code (0 = OK, see grpc::StatusCode).

Private Members

int code_

struct ShortestPathResult

#include <types.hpp>

Result of a shortest path query.

Contains one or more shortest paths between two revisions.

Public Functions

inline const RevisionPath *first_path() const

Get the first path, or nullptr if none found.

Public Members

std::vector<RevisionPath> paths

One or more shortest paths found.

bool path_exists

True if any path was found.

int path_length

Length of the shortest path(s).

class Space

#include <space.hpp>

A hierarchical container for organizing items in Kumiho.

Spaces form the folder structure within a project. They can contain other spaces (sub-spaces) and items, allowing you to organize assets in a meaningful hierarchy.

Spaces are identified by their full path (e.g., “/project/characters/heroes”) and can store custom metadata.

Example:

auto assets = project->createSpace("assets");
auto models = assets->createSpace("models");
auto textures = assets->createSpace("textures");

// Create items
auto chair = models->createItem("chair", "model");

// Navigate hierarchy
auto parent = models->getParentSpace();  // Returns assets
auto children = assets->getChildSpaces();  // Returns [models, textures]

Public Functions

Space(const ::kumiho::SpaceResponse &response, Client *client)

Construct a Space from a protobuf response.

Parameters:

• response – The protobuf SpaceResponse message.

• client – The client for making API calls.

std::string getPath() const

Get the space’s full path.

Returns:

The full path (e.g., “/project/assets/models”).

Kref getKref() const

Get the space’s Kref.

Returns:

A Kref containing the space path.

std::string getName() const

Get the space’s name (last component of path).

Returns:

The space name.

std::string getType() const

Get the space’s type.

Returns:

“root” for project-level, “sub” for nested spaces.

Metadata getMetadata() const

Get the space’s metadata.

Returns:

A map of metadata key-value pairs.

std::optional<std::string> getCreatedAt() const

Get the creation timestamp.

Returns:

ISO timestamp when the space was created, or nullopt.

std::string getAuthor() const

Get the author’s user ID.

Returns:

The UUID of the user who created the space.

std::string getUsername() const

Get the author’s display name.

Returns:

The username of the space creator.

std::shared_ptr<Space> createSpace(const std::string &name)

Create a sub-space.

Parameters:

name – The name of the new space.

Returns:

The created Space.

std::shared_ptr<Item> createItem(const std::string &name, const std::string &kind)

Create an item in this space.

Parameters:

• name – The item name.

• kind – The item kind (e.g., “model”, “texture”).

Throws:

ReservedKindError – if kind is reserved (e.g., “bundle”).

Returns:

The created Item.

std::shared_ptr<Item> getItem(const std::string &name, const std::string &kind)

Get an item by name and kind.

Parameters:

• name – The item name.

• kind – The item kind.

Returns:

The Item.

PagedList<std::shared_ptr<Item>> getItems(const std::string &name_filter = "", const std::string &kind_filter = "", std::optional<int32_t> page_size = std::nullopt, std::optional<std::string> cursor = std::nullopt, bool include_deprecated = false)

Get all items in this space.

Parameters:

• name_filter – Optional filter by item name (supports wildcards).

• kind_filter – Optional filter by item kind.

• page_size – Optional page size for pagination.

• cursor – Optional cursor for pagination.

• include_deprecated – Whether to include deprecated items.

Returns:

A PagedList of Item objects.

std::shared_ptr<Space> setMetadata(const Metadata &metadata)

Set or update metadata for this space.

Parameters:

metadata – Dictionary of metadata key-value pairs.

Returns:

The updated Space.

std::optional<std::string> getAttribute(const std::string &key)

Get a single metadata attribute.

Parameters:

key – The attribute key to retrieve.

Returns:

The attribute value, or nullopt if not found.

bool setAttribute(const std::string &key, const std::string &value)

Set a single metadata attribute.

Parameters:

• key – The attribute key to set.

• value – The attribute value.

Returns:

True if the attribute was set successfully.

bool deleteAttribute(const std::string &key)

Delete a single metadata attribute.

Parameters:

key – The attribute key to delete.

Returns:

True if the attribute was deleted successfully.

void deleteSpace(bool force = false)

Delete this space.

Parameters:

force – If true, permanently delete. If false, soft delete.

std::shared_ptr<Space> getParentSpace()

Get the parent space.

Returns:

The parent Space, or nullptr if this is a root space.

std::vector<std::shared_ptr<Space>> getChildSpaces()

Get child spaces.

Returns:

A list of child Space objects.

std::shared_ptr<Project> getProject()

Get the parent project.

Returns:

The Project containing this space.

std::shared_ptr<Bundle> createBundle(const std::string &name)

Create a bundle in this space.

Parameters:

name – The bundle name.

Returns:

The created Bundle.

std::shared_ptr<Bundle> getBundle(const std::string &name)

Get a bundle by name.

Parameters:

name – The bundle name.

Returns:

The Bundle.

Private Members

::kumiho::SpaceResponse response_

Client *client_

struct TenantUsage

#include <types.hpp>

Tenant usage and limits information.

Contains the current resource usage and quota limits for the tenant.

Public Functions

inline double usagePercent() const

Calculate usage percentage.

inline bool isNearLimit() const

Check if tenant is near the limit (>80% usage).

inline bool isAtLimit() const

Check if tenant has reached the limit.

Public Members

int64_t node_count = 0

Current number of nodes (entities) in the tenant.

int64_t node_limit = 0

Maximum allowed nodes for the tenant’s plan.

std::string tenant_id

The tenant’s unique identifier.

struct TraversalResult

#include <types.hpp>

Result of a graph traversal operation.

Contains all discovered revisions and optionally the paths to reach them.

Public Members

std::vector<RevisionPath> paths

Full paths to each discovered revision (if include_path=true).

std::vector<std::string> revision_krefs

Flat list of all discovered revision Krefs.

std::vector<std::shared_ptr<Edge>> edges

All edges traversed during the operation.

int total_count = 0

Total number of nodes found.

bool truncated = false

True if results were limited/truncated.

class ValidationError : public kumiho::api::KumihoError

#include <error.hpp>

Exception for input validation failures.

Thrown when user-provided input fails validation (e.g., invalid kref format, invalid time format, reserved product type).

Subclassed by kumiho::api::EdgeTypeValidationError, kumiho::api::KrefValidationError, kumiho::api::ReservedKindError

Public Functions

inline explicit ValidationError(const std::string &message)

namespace kumiho

Root namespace for the Kumiho SDK.

namespace api

Public API namespace containing all Kumiho classes and functions.

Typedefs

typedef Artifact Resource

using LinkTypeValidationError = EdgeTypeValidationError

using ReservedProductTypeError = ReservedKindError

using Metadata = std::map<std::string, std::string>

Metadata type used throughout Kumiho.

Metadata is a key-value store of string pairs attached to most entities.

Enums

enum class EdgeDirection : int

Direction constants for edge traversal queries.

When querying edges, specify which direction to traverse: outgoing edges (from source), incoming edges (to target), or both.

Example:

// Get dependencies (what this revision depends on)
auto deps = revision->getEdges(EdgeType::DEPENDS_ON, EdgeDirection::OUTGOING);

// Get dependents (what depends on this revision)
auto dependents = revision->getEdges(EdgeType::DEPENDS_ON, EdgeDirection::INCOMING);

Values:

enumerator OUTGOING

Edges where the queried revision is the source.

enumerator INCOMING

Edges where the queried revision is the target.

enumerator BOTH

Edges in either direction.

Functions

std::shared_ptr<Space> createSpace(std::shared_ptr<Client> client, const std::string &path)

Create nested spaces from a path.

Creates intermediate spaces if they don’t exist.

Parameters:

• client – The client to use.

• path – The full path of spaces to create (e.g., “project/seq/shot”).

Returns:

The final Space in the path.

inline std::shared_ptr<Space> createGroup(std::shared_ptr<Client> client, const std::string &path)

std::string getCurrentUser()

Get the current username from environment.

Returns:

The username, or “unknown” if not found.

std::string getDefaultControlPlaneUrl()

Get the default control plane URL.

Returns the value of KUMIHO_CONTROL_PLANE_URL environment variable, or “https://control.kumiho.cloud” if not set.

Returns:

The control plane URL.

std::filesystem::path getDefaultCachePath()

Get the default discovery cache path.

Returns the value of KUMIHO_DISCOVERY_CACHE_FILE environment variable, or ~/.kumiho/discovery-cache.json if not set.

Returns:

The cache file path.

std::shared_ptr<Client> clientFromDiscovery(const std::optional<std::string> &id_token = std::nullopt, const std::optional<std::string> &tenant_hint = std::nullopt, const std::string &control_plane_url = "", const std::string &cache_path = "", bool force_refresh = false)

inline void validateEdgeType(const std::string &edge_type)

Validate an edge type for security and correctness.

Edge types must:

• Start with an uppercase letter

• Contain only uppercase letters, digits, and underscores

• Be 1-50 characters long

Example:

validateEdgeType("DEPENDS_ON");  // OK
validateEdgeType("depends_on");  // Throws error

Parameters:

edge_type – The edge type to validate.

Throws:

EdgeTypeValidationError – if the edge type is invalid.

inline bool isValidEdgeType(const std::string &edge_type)

Check if an edge type is valid without throwing exceptions.

Parameters:

edge_type – The edge type to validate.

Returns:

True if the edge type is valid, false otherwise.

void validateKref(const std::string &kref_uri)

Validate a Kref URI string.

Validates that the string is a properly formatted Kref URI. Does not check if the referenced entity exists.

Parameters:

kref_uri – The URI string to validate.

Throws:

KrefValidationError – if the format is invalid.

bool isValidKref(const std::string &kref_uri)

Check if a string is a valid Kref URI.

Non-throwing version of validateKref().

Parameters:

kref_uri – The URI string to check.

Returns:

True if valid, false otherwise.

std::filesystem::path getConfigDir()

Get the Kumiho configuration directory.

Returns the value of KUMIHO_CONFIG_DIR if set, otherwise returns the user’s home directory plus .kumiho (e.g., ~/.kumiho on Unix, C:\Users<user>.kumiho on Windows).

Returns:

The path to the configuration directory.

std::filesystem::path getCredentialsPath()

Get the path to the credentials file.

Returns:

The path to kumiho_authentication.json.

std::optional<std::string> loadBearerToken()

Load the preferred bearer token for gRPC calls.

Token resolution order:

1. KUMIHO_AUTH_TOKEN environment variable

2. Firebase ID token from credentials file (if KUMIHO_USE_CONTROL_PLANE_TOKEN not set)

3. Control plane token from credentials file

Throws:

ValidationError – if a token is found but has invalid JWT format.

Returns:

The bearer token, or nullopt if no token is available.

std::optional<std::string> loadFirebaseToken()

Load the Firebase ID token for control-plane interactions.

Token resolution order:

1. KUMIHO_FIREBASE_ID_TOKEN environment variable

2. id_token field from credentials file

Throws:

ValidationError – if a token is found but has invalid JWT format.

Returns:

The Firebase ID token, or nullopt if not available.

std::string validateTokenFormat(const std::string &token, const std::string &source = "token")

Validate that a token has valid JWT structure.

Checks that the token has exactly 3 non-empty parts separated by dots. This catches common errors like using API keys instead of JWTs.

Parameters:

• token – The token string to validate.

• source – Description of the token source (for error messages).

Throws:

ValidationError – if the token format is invalid.

Returns:

The validated token string.

bool isControlPlaneToken(const std::string &token)

Check if a JWT token is a control-plane token.

Control plane tokens have specific claims that identify them:

• tenant_id claim

• iss starting with “https://kumiho.io”

• aud starting with “https://api.kumiho.io”

Parameters:

token – The JWT token string.

Returns:

True if this is a control-plane token.

std::map<std::string, std::string> decodeJwtClaims(const std::string &token)

Decode JWT claims from a token.

Extracts the payload section from a JWT and returns the claims as a string map. Only works for simple string claims.

Parameters:

token – The JWT token string.

Returns:

A map of claim names to values.

inline bool isReservedKind(const std::string &kind)

Check if an item kind is reserved.

Parameters:

kind – The item kind to check.

Returns:

True if the kind is reserved, false otherwise.

Variables

constexpr const char *DEPENDS_ON = EdgeType::DEPENDS_ON

Alias for EdgeType::DEPENDS_ON.

constexpr const char *DERIVED_FROM = EdgeType::DERIVED_FROM

Alias for EdgeType::DERIVED_FROM.

constexpr const char *CREATED_FROM = EdgeType::CREATED_FROM

Alias for EdgeType::CREATED_FROM.

constexpr const char *REFERENCED = EdgeType::REFERENCED

Alias for EdgeType::REFERENCED.

constexpr const char *CONTAINS = EdgeType::CONTAINS

Alias for EdgeType::CONTAINS.

constexpr const char *BELONGS_TO = EdgeType::BELONGS_TO

Alias for EdgeType::BELONGS_TO.

constexpr EdgeDirection OUTGOING = EdgeDirection::OUTGOING

Alias for EdgeDirection::OUTGOING.

constexpr EdgeDirection INCOMING = EdgeDirection::INCOMING

Alias for EdgeDirection::INCOMING.

constexpr EdgeDirection BOTH = EdgeDirection::BOTH

Alias for EdgeDirection::BOTH.

constexpr const char *TOKEN_ENV = "KUMIHO_AUTH_TOKEN"

Environment variable for auth token override.

constexpr const char *FIREBASE_TOKEN_ENV = "KUMIHO_FIREBASE_ID_TOKEN"

Environment variable for Firebase ID token override.

constexpr const char *USE_CP_TOKEN_ENV = "KUMIHO_USE_CONTROL_PLANE_TOKEN"

Environment variable to prefer control plane token.

constexpr const char *CONFIG_DIR_ENV = "KUMIHO_CONFIG_DIR"

Environment variable for config directory override.

constexpr const char *CREDENTIALS_FILENAME = "kumiho_authentication.json"

Credentials filename.

constexpr const char *LATEST_TAG = "latest"

Standard tag name for the latest version.

This tag automatically moves to the newest version of a product.

constexpr const char *PUBLISHED_TAG = "published"

Standard tag name for published versions.

Published versions are immutable - their metadata cannot be changed.

const std::vector<std::string> RESERVED_KINDS = {"bundle"}

Reserved item kinds that cannot be created manually.

Use dedicated methods (e.g., createBundle) for these kinds.

namespace api

namespace api

namespace api

namespace api

namespace std

file artifact.hpp

#include <string>

#include <memory>

#include <optional>

#include “kumiho/types.hpp”

#include “kumiho/kref.hpp”

#include “kumiho.grpc.pb.h”

Artifact entity representing file references within revisions.

Artifacts are the leaf nodes of the Kumiho hierarchy. They point to actual files on local disk, network storage, or cloud URIs. Kumiho tracks the path and metadata but does not upload or modify the files.

file bundle.hpp

#include <string>

#include <vector>

#include <memory>

#include <optional>

#include “kumiho/types.hpp”

#include “kumiho/kref.hpp”

#include “kumiho/item.hpp”

#include “kumiho.grpc.pb.h”

Bundle entity for aggregating items.

Bundles are special items that aggregate other items. They maintain an audit trail of membership changes through revisioning.

file client.hpp

#include <string>

#include <vector>

#include <memory>

#include <optional>

#include <grpcpp/grpcpp.h>

#include “kumiho/types.hpp”

#include “kumiho/kref.hpp”

#include “kumiho/error.hpp”

#include “kumiho/bundle.hpp”

#include “kumiho.grpc.pb.h”

Low-level gRPC client for the Kumiho Cloud service.

This module provides the Client class that handles all gRPC communication with Kumiho Cloud servers. It manages connection establishment, authentication, and all gRPC method calls.

Terminology:

• Space: A hierarchical container/namespace

• Item: An asset/entity in the graph

• Revision: A specific state of an item

• Artifact: A file/location attached to a revision

• Edge: A relationship between revisions

• Bundle: A curated set of items

file discovery.hpp

#include <string>

#include <vector>

#include <memory>

#include <optional>

#include <map>

#include <chrono>

#include <filesystem>

Discovery and auto-configuration for the Kumiho C++ SDK.

This header provides classes and functions for bootstrapping a Client via the control-plane discovery endpoint. It handles caching of discovery payloads, respects cache-control metadata, and automatically refreshes routing info.

file edge.hpp

#include <string>

#include <map>

#include <optional>

#include <regex>

#include “kumiho/types.hpp”

#include “kumiho/kref.hpp”

#include “kumiho/error.hpp”

#include “kumiho.grpc.pb.h”

Edge entity for tracking relationships between revisions.

Edges represent directed relationships between revisions in the Kumiho graph database. They enable dependency tracking, lineage visualization, and impact analysis.

file error.hpp

#include <stdexcept>

#include <string>

Exception hierarchy for the Kumiho C++ SDK.

This header defines all exception types used throughout the Kumiho library, providing structured error handling for different failure scenarios.

file event.hpp

#include <string>

#include <map>

#include <memory>

#include <grpcpp/grpcpp.h>

#include “kumiho/types.hpp”

#include “kumiho/kref.hpp”

#include “kumiho.grpc.pb.h”

Event and EventStream for real-time notifications.

Kumiho provides a gRPC streaming API for receiving real-time events about changes to the graph database.

file item.hpp

#include <string>

#include <vector>

#include <memory>

#include <optional>

#include <chrono>

#include “kumiho/types.hpp”

#include “kumiho/kref.hpp”

#include “kumiho.grpc.pb.h”

Item entity representing versioned assets.

Items represent assets that can have multiple revisions, such as 3D models, textures, workflows, or any other type of creative content. Each item belongs to a space and is identified by a combination of name and kind.

file kref.hpp

#include <string>

#include <optional>

#include <regex>

#include “kumiho.grpc.pb.h”

Kref (Kumiho Reference) URI parser and utilities.

Kref is the URI-based unique identifier system for Kumiho objects. Format: kref://project/space/item.kind?r=1&a=artifact

Terminology:

• Space: A hierarchical container/namespace

• Item: An asset/entity in the graph

• Revision: A specific state of an item

• Artifact: A file/location attached to a revision

• Kind: The category of an item

file kumiho.hpp

#include “kumiho/types.hpp”

#include “kumiho/error.hpp”

#include “kumiho/kref.hpp”

#include “kumiho/project.hpp”

#include “kumiho/space.hpp”

#include “kumiho/item.hpp”

#include “kumiho/revision.hpp”

#include “kumiho/artifact.hpp”

#include “kumiho/edge.hpp”

#include “kumiho/bundle.hpp”

#include “kumiho/event.hpp”

#include “kumiho/token_loader.hpp”

#include “kumiho/discovery.hpp”

#include “kumiho/client.hpp”

Main include header for the Kumiho C++ SDK.

This is the primary header to include when using the Kumiho SDK. It includes all public headers.

Terminology:

• Space: A hierarchical container/namespace

• Item: An asset/entity in the graph

• Revision: A specific state of an item

• Artifact: A file/location attached to a revision

• Edge: A relationship between revisions

• Bundle: A curated set of items

file project.hpp

#include <string>

#include <vector>

#include <memory>

#include <optional>

#include “kumiho/types.hpp”

#include “kumiho/kref.hpp”

#include “kumiho.grpc.pb.h”

Project entity - the top-level container for assets.

Projects are the root of the Kumiho hierarchy. Each project has its own namespace for groups and products, and manages access control and settings independently.

file revision.hpp

#include <string>

#include <vector>

#include <memory>

#include <optional>

#include “kumiho/types.hpp”

#include “kumiho/kref.hpp”

#include “kumiho/edge.hpp”

#include “kumiho.grpc.pb.h”

Revision entity representing iterations of an item.

Revisions are immutable snapshots of an item at a point in time. Each revision can have multiple artifacts (file references), tags for categorization, and edges to other revisions for dependency tracking.

file space.hpp

#include <string>

#include <vector>

#include <memory>

#include <optional>

#include “kumiho/types.hpp”

#include “kumiho/kref.hpp”

#include “kumiho.grpc.pb.h”

Space entity for hierarchical organization of items.

Spaces form the folder structure within a project. They can contain other spaces (sub-spaces) and items, allowing you to organize assets in a meaningful hierarchy.

file token_loader.hpp

#include <string>

#include <optional>

#include <map>

#include <filesystem>

Token loading utilities for the Kumiho C++ SDK.

This header provides functions for locating and loading bearer tokens used for authentication with Kumiho Cloud services.

file types.hpp

#include <map>

#include <string>

#include <vector>

#include <optional>

#include <memory>

Common type definitions and constants for the Kumiho C++ SDK.

This header defines type aliases, constants, and common enumerations used throughout the Kumiho library.

file README.md

file artifact.cpp

#include “kumiho/artifact.hpp”

#include “kumiho/client.hpp”

#include “kumiho/revision.hpp”

#include “kumiho/item.hpp”

#include “kumiho/space.hpp”

#include “kumiho/project.hpp”

#include “kumiho/error.hpp”

Implementation of Artifact class.

file bundle.cpp

#include “kumiho/bundle.hpp”

#include “kumiho/client.hpp”

#include “kumiho/error.hpp”

Implementation of Bundle class.

file client.cpp

#include “kumiho/client.hpp”

#include “kumiho/project.hpp”

#include “kumiho/space.hpp”

#include “kumiho/item.hpp”

#include “kumiho/revision.hpp”

#include “kumiho/artifact.hpp”

#include “kumiho/edge.hpp”

#include “kumiho/bundle.hpp”

#include “kumiho/event.hpp”

#include “kumiho/error.hpp”

#include “kumiho/token_loader.hpp”

#include <grpcpp/grpcpp.h>

#include <regex>

#include <sstream>

#include <fstream>

#include <cctype>

#include <cstdlib>

#include <algorithm>

#include <chrono>

#include <random>

#include <iomanip>

Implementation of Client class with all gRPC operations.

Terminology (with backwards compatibility):

• Space (formerly Group): A hierarchical container/namespace

• Item (formerly Product): An asset/entity in the graph

• Revision (formerly Version): A specific state of an item

• Artifact (formerly Resource): A file/location attached to a revision

• Edge (formerly Link): A relationship between revisions

• Bundle (formerly Collection): A curated set of items

Variables

std::string address

std::string authority

bool use_tls

file collection.cpp

#include “kumiho/collection.hpp”

#include “kumiho/client.hpp”

#include “kumiho/error.hpp”

Implementation of Collection class.

file discovery.cpp

#include “kumiho/discovery.hpp”

#include “kumiho/token_loader.hpp”

#include “kumiho/error.hpp”

#include “kumiho/client.hpp”

#include <curl/curl.h>

#include <nlohmann/json.hpp>

#include <fstream>

#include <sstream>

#include <cstdlib>

#include <ctime>

#include <regex>

#include <random>

#include <iomanip>

#include <array>

#include <algorithm>

#include <mutex>

#include <unistd.h>

Implementation of discovery and auto-configuration.

file edge.cpp

#include “kumiho/edge.hpp”

#include “kumiho/client.hpp”

Implementation of Edge class.

file event.cpp

#include “kumiho/event.hpp”

Implementation of Event and EventStream classes.

file group.cpp

#include “kumiho/group.hpp”

#include “kumiho/client.hpp”

#include “kumiho/product.hpp”

#include “kumiho/project.hpp”

#include “kumiho/collection.hpp”

#include “kumiho/error.hpp”

#include <sstream>

Implementation of Group class.

file item.cpp

#include “kumiho/item.hpp”

#include “kumiho/client.hpp”

#include “kumiho/revision.hpp”

#include “kumiho/space.hpp”

#include “kumiho/project.hpp”

#include “kumiho/error.hpp”

#include <algorithm>

#include <iomanip>

#include <sstream>

Implementation of Item class.

file kref.cpp

#include “kumiho/kref.hpp”

#include “kumiho/error.hpp”

#include <regex>

#include <sstream>

Implementation of Kref URI parsing and validation.

Terminology (with backwards compatibility):

• Space (formerly Group): A hierarchical container/namespace

• Item (formerly Product): An asset/entity in the graph

• Revision (formerly Version): A specific state of an item

• Artifact (formerly Resource): A file/location attached to a revision

• Kind (formerly Type): The category of an item

file link.cpp

#include “kumiho/link.hpp”

#include “kumiho/client.hpp”

Implementation of Link class.

file product.cpp

#include “kumiho/product.hpp”

#include “kumiho/client.hpp”

#include “kumiho/version.hpp”

#include “kumiho/group.hpp”

#include “kumiho/project.hpp”

#include “kumiho/error.hpp”

#include <algorithm>

Implementation of Product class.

file project.cpp

#include “kumiho/project.hpp”

#include “kumiho/client.hpp”

#include “kumiho/space.hpp”

#include “kumiho/bundle.hpp”

#include “kumiho/error.hpp”

Implementation of Project class.

file resource.cpp

#include “kumiho/resource.hpp”

#include “kumiho/client.hpp”

#include “kumiho/version.hpp”

#include “kumiho/product.hpp”

#include “kumiho/group.hpp”

#include “kumiho/project.hpp”

#include “kumiho/error.hpp”

Implementation of Resource class.

file revision.cpp

#include “kumiho/revision.hpp”

#include “kumiho/client.hpp”

#include “kumiho/artifact.hpp”

#include “kumiho/item.hpp”

#include “kumiho/space.hpp”

#include “kumiho/project.hpp”

#include “kumiho/edge.hpp”

#include “kumiho/error.hpp”

#include <algorithm>

Implementation of Revision class.

file space.cpp

#include “kumiho/space.hpp”

#include “kumiho/client.hpp”

#include “kumiho/item.hpp”

#include “kumiho/project.hpp”

#include “kumiho/bundle.hpp”

#include “kumiho/error.hpp”

#include <sstream>

Implementation of Space class.

file token_loader.cpp

#include “kumiho/token_loader.hpp”

#include “kumiho/error.hpp”

#include <fstream>

#include <sstream>

#include <cstdlib>

#include <regex>

#include <algorithm>

#include <iostream>

#include <sys/stat.h>

Implementation of token loading utilities.

Variables

std::optional<std::string> control_plane_token

std::optional<std::string> id_token

file version.cpp

#include “kumiho/version.hpp”

#include “kumiho/client.hpp”

#include “kumiho/resource.hpp”

#include “kumiho/product.hpp”

#include “kumiho/group.hpp”

#include “kumiho/project.hpp”

#include “kumiho/link.hpp”

#include “kumiho/error.hpp”

#include <algorithm>

Implementation of Version class.

page Deprecated List

Member kumiho::api::Artifact::deleteResource  (bool force=false)

Use deleteArtifact() instead.

Member kumiho::api::Artifact::getGroup  ()

Use getSpace() instead.

Member kumiho::api::Artifact::getProduct  ()

Use getItem() instead.

Member kumiho::api::Artifact::getProductKref  () const

Use getItemKref() instead.

Member kumiho::api::Artifact::getVersion  ()

Use getRevision() instead.

Member kumiho::api::Artifact::getVersionKref  () const

Use getRevisionKref() instead.

dir include

dir include/kumiho

dir src

example /home/runner/work/kumiho-cpp/kumiho-cpp/include/kumiho/discovery.hpp

Create a Client configured via the discovery endpoint.

Create a Client configured via the discovery endpoint.This is the recommended way to create a Client for production use. It automatically discovers the correct data plane endpoint based on the user’s tenant and region.

// Simple usage (uses cached credentials)
auto client = kumiho::api::clientFromDiscovery();

// With explicit token
auto client = kumiho::api::clientFromDiscovery("your-id-token");

// Force refresh for testing
auto client = kumiho::api::clientFromDiscovery(
    std::nullopt, std::nullopt, "", "", true
);

#pragma once

#include <string>
#include <vector>
#include <memory>
#include <optional>
#include <map>
#include <chrono>
#include <filesystem>

namespace kumiho {
namespace api {

// Forward declarations
class Client;

struct RegionRouting {
    std::string region_code;
    
    std::string server_url;
    
    std::optional<std::string> grpc_authority;
};

struct CacheControl {
    std::chrono::system_clock::time_point issued_at;
    
    std::chrono::system_clock::time_point refresh_at;
    
    std::chrono::system_clock::time_point expires_at;
    
    int expires_in_seconds;
    
    int refresh_after_seconds;

    bool isExpired() const;

    bool shouldRefresh() const;
};

struct DiscoveryRecord {
    std::string tenant_id;
    
    std::optional<std::string> tenant_name;
    
    std::vector<std::string> roles;
    
    std::optional<std::map<std::string, std::string>> guardrails;
    
    RegionRouting region;
    
    CacheControl cache_control;
};

class DiscoveryCache {
public:
    explicit DiscoveryCache(const std::filesystem::path& path = {}, bool encrypt = true);

    std::optional<DiscoveryRecord> load(const std::string& cache_key);

    void store(const std::string& cache_key, const DiscoveryRecord& record);

    const std::filesystem::path& getPath() const { return path_; }

private:
    std::filesystem::path path_;
    bool encrypt_;
    
    std::map<std::string, std::map<std::string, std::string>> readAll();
    
    std::string encryptContent(const std::string& plaintext);
    
    std::string decryptContent(const std::string& encrypted);
    
    std::vector<uint8_t> deriveKey();
};

class DiscoveryManager {
public:
    explicit DiscoveryManager(
        const std::string& control_plane_url = "",
        const std::filesystem::path& cache_path = {},
        double timeout_seconds = 10.0
    );

    DiscoveryRecord resolve(
        const std::string& id_token,
        const std::optional<std::string>& tenant_hint = std::nullopt,
        bool force_refresh = false
    );

private:
    std::string base_url_;
    DiscoveryCache cache_;
    double timeout_;

    DiscoveryRecord fetchRemote(
        const std::string& id_token,
        const std::optional<std::string>& tenant_hint
    );
};

// --- Convenience Functions ---

std::string getDefaultControlPlaneUrl();

std::filesystem::path getDefaultCachePath();

std::shared_ptr<Client> clientFromDiscovery(
    const std::optional<std::string>& id_token = std::nullopt,
    const std::optional<std::string>& tenant_hint = std::nullopt,
    const std::string& control_plane_url = "",
    const std::string& cache_path = "",
    bool force_refresh = false
);

} // namespace api
} // namespace kumiho

param id_token:

Optional ID token (defaults to loaded bearer token).

param tenant_hint:

Optional tenant ID hint.

param control_plane_url:

Optional control plane URL override.

param cache_path:

Optional cache file path override.

param force_refresh:

Force refresh of cached discovery data.

throws DiscoveryError:

if discovery fails.

throws AuthenticationError:

if no token is available.

return:

A shared pointer to the configured Client.

example /home/runner/work/kumiho-cpp/kumiho-cpp/include/kumiho/kumiho.hpp

#include <kumiho/kumiho.hpp>

int main() {
    auto client = kumiho::api::Client::createFromEnv();
    auto project = client->createProject("my-project");
    auto space = project->createSpace("assets");
    auto item = space->createItem("hero", "model");
    auto revision = item->createRevision({{"artist", "jane"}});
    revision->createArtifact("mesh", "/assets/hero.fbx");
    revision->tag("approved");
    return 0;
}

#pragma once

// Core types and utilities
#include "kumiho/types.hpp"
#include "kumiho/error.hpp"
#include "kumiho/kref.hpp"

// Entity classes
#include "kumiho/project.hpp"
#include "kumiho/space.hpp"
#include "kumiho/item.hpp"
#include "kumiho/revision.hpp"
#include "kumiho/artifact.hpp"
#include "kumiho/edge.hpp"
#include "kumiho/bundle.hpp"
#include "kumiho/event.hpp"

// Discovery and authentication
#include "kumiho/token_loader.hpp"
#include "kumiho/discovery.hpp"

// Client
#include "kumiho/client.hpp"

namespace kumiho {

namespace api {

// Convenience aliases for commonly used edge types

constexpr const char* DEPENDS_ON = EdgeType::DEPENDS_ON;

constexpr const char* DERIVED_FROM = EdgeType::DERIVED_FROM;

constexpr const char* CREATED_FROM = EdgeType::CREATED_FROM;

constexpr const char* REFERENCED = EdgeType::REFERENCED;

constexpr const char* CONTAINS = EdgeType::CONTAINS;

constexpr const char* BELONGS_TO = EdgeType::BELONGS_TO;

constexpr EdgeDirection OUTGOING = EdgeDirection::OUTGOING;

constexpr EdgeDirection INCOMING = EdgeDirection::INCOMING;

constexpr EdgeDirection BOTH = EdgeDirection::BOTH;

} // namespace api
} // namespace kumiho

page Kumiho C++ SDK

Modern C++ client library for the Kumiho asset management and versioning platform.

[

](LICENSE)

Features

• Full API Parity: Complete feature parity with the Python Kumiho SDK

• Modern C++17: Uses std::optional, std::string_view, structured bindings

• gRPC Backend: High-performance communication with Kumiho servers

• Type-Safe: Strong typing with compile-time checks

• Graph Traversal: Dependency tracking and impact analysis

• Streaming Events: Real-time change notifications

• Discovery Service: Automatic endpoint resolution

Terminology

New Term	Description
Space	Hierarchical container/namespace
Item	Asset/entity in the graph
Revision	Specific state of an item
Artifact	File/location attached to a revision
Edge	Relationship between revisions
Bundle	Curated set of items
Kind	Category/classification of an item

Note: All old method names and types are still supported as backwards-compatible aliases.

Quick Start

Prerequisites

• C++17 compatible compiler (MSVC 2019+, GCC 8+, Clang 8+)

• CMake 3.10+

• vcpkg (recommended for dependency management)

• gRPC and Protobuf

Installation via vcpkg

# Install dependencies
vcpkg install grpc protobuf gtest

# Clone and build
git clone https://github.com/kumihoclouds/kumiho-cpp.git
cd kumiho-cpp
mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
cmake --build . --config Release

Basic Usage

#include <kumiho/kumiho.hpp>
#include <iostream>

using namespace kumiho::api;

int main() {
    // Connect to server
    auto client = Client::createFromEnv();
    
    // Create a project
    auto project = client->createProject("my-project", "My first project");
    std::cout << "Created project: " << project->getName() << std::endl;
    
    // Create a space hierarchy
    auto assets = project->createSpace("assets");
    auto characters = assets->createSpace("characters");
    
    // Create an item with revision
    auto hero = characters->createItem("hero", "model");
    auto v1 = hero->createRevision({{"author", "artist1"}});
    
    // Add an artifact
    v1->createArtifact("main_mesh", "/path/to/hero.obj");
    
    std::cout << "Created revision " << v1->getNumber() << std::endl;
    
    return 0;
}

Core Concepts

Kref (Kumiho Reference)

Krefs are URI-style identifiers for all entities:

// Parse a Kref
Kref kref("kref://my-project/assets/hero.model?r=1");

std::cout << "Project: " << kref.getProject() << std::endl;    // my-project
std::cout << "Space: " << kref.getSpace() << std::endl;        // assets
std::cout << "Item: " << kref.getItemName() << std::endl;      // hero
std::cout << "Kind: " << kref.getKind() << std::endl;          // model
std::cout << "Revision: " << *kref.getRevision() << std::endl; // 1

// Check validity
if (kref.isValid()) {
    // Use the kref
}

// Convert to string
std::string uri = kref.uri();

Entity Hierarchy

Project
├── Space (can be nested)
│   ├── Space
│   │   └── Item.kind
│   │       ├── Revision 1
│   │       │   └── Artifact
│   │       └── Revision 2
│   └── Item.kind
└── Bundle (curated item collections)

Edges and Dependencies

// Create revisions
auto modelR1 = model.createRevision({});
auto rigR1 = rig.createRevision({});

// Create a dependency edge
auto edge = modelR1.createEdge(rigR1.kref(), EdgeType::DEPENDS_ON);

// Query edges
auto outgoing = modelR1.getEdges(EdgeDirection::OUTGOING);
auto incoming = rigR1.getEdges(EdgeDirection::INCOMING);

// Traverse the graph
auto deps = modelR1.getAllDependencies({}, 5, 100);
for (const auto& kref : deps.revision_krefs) {
    std::cout << "Depends on: " << kref << std::endl;
}

// Find shortest path
auto path = modelR1.findPathTo(targetKref, {}, 10, false);
if (path.path_exists) {
    std::cout << "Path length: " << path.path_length << std::endl;
}

// Impact analysis
auto impact = rigR1.analyzeImpact({}, 5, 100);
for (const auto& impacted : impact.impacted_revisions) {
    std::cout << "Would impact: " << impacted.revision_kref << std::endl;
}

Bundles

// Create a bundle
auto bundle = project.createBundle("my_bundle");

// Add members
bundle.addMember(item1);
bundle.addMember(item2);

// List members
for (const auto& member : bundle.getMembers()) {
    std::cout << "Member: " << member.item_kref.uri() << std::endl;
}

// View history
for (const auto& entry : bundle.getHistory()) {
    std::cout << entry.action << " at " << entry.created_at << std::endl;
}

Event Streaming

// Subscribe to events
client->subscribeEvents("my-project", [](const Event& event) {
    std::cout << "Event: " << event.eventType() << std::endl;
    std::cout << "Entity: " << event.entityKref().toString() << std::endl;
    return true;  // Continue listening
});

// Or use EventStream for manual control
auto stream = client->openEventStream("my-project");
while (true) {
    auto event = stream->next();
    if (!event) break;
    // Process event
}

Time-Based Revision Queries

One of Kumiho’s most powerful features is time-based revision lookup. This enables reproducible builds, historical debugging, and auditing by answering questions like: “What was the published revision of this asset on June 1st?”

Why Time-Based Queries Matter

In production pipelines, you often need to:

1. Reproduce past renders: Re-render a shot exactly as it was delivered months ago

2. Debug regressions: Compare current assets against a known-good state from a specific date

3. Audit changes: Understand what revision was used when a decision was made

4. Compliance: Prove what asset revisions were in use at a particular milestone

Supported Time Formats

The time parameter accepts multiple formats:

Format	Example	Precision
YYYYMMDDHHMM	"202406011330"	Minute-level
ISO 8601	"2024-06-01T13:30:00Z"	Second-level
std::chrono	system_clock::time_point	Sub-second

Using Time-Based Methods

#include <chrono>

// Get revision by tag
auto published = item->getRevisionByTag("published");

// Get revision by time (YYYYMMDDHHMM format)
auto historyRev = item->getRevisionByTime("202406011330");

// Using ISO 8601 format for sub-second precision
auto historyRev2 = item->getRevisionByTime("2024-06-01T13:30:45Z");

// Using std::chrono (C++ datetime)
auto june_1 = std::chrono::system_clock::from_time_t(1717243200);  // June 1, 2024
auto historyRev3 = item->getRevisionByTime(june_1);

// Get revision by BOTH tag and time
// "What was the published revision on June 1st?"
auto publishedAtTime = item->getRevisionByTagAndTime("published", "202406011330");
if (publishedAtTime) {
    std::cout << "On June 1, published revision was r" 
              << publishedAtTime->getRevisionNumber() << std::endl;
}

// Using std::chrono with tag
auto publishedAtTime2 = item->getRevisionByTagAndTime("published", june_1);

Time-Based Kref URIs

You can also use time-based queries directly in Kref URIs:

// Get published revision at a specific time
auto revision = client->resolveKref(
    "kref://my-project/chars/hero.model",
    "published",      // tag
    "202406011330"    // time (YYYYMMDDHHMM or ISO 8601)
);

// Using ISO 8601 format
auto revision2 = client->resolveKref(
    "kref://my-project/chars/hero.model",
    "published",
    "2024-06-01T13:30:00Z"
);

// Resolve to artifact location at that point in time
auto location = client->resolve("kref://my-project/chars/hero.model?t=published&time=202406011330");

Kref time query parameters:

Parameter	Description
t=<tag>	Find revision with this tag (e.g., t=published, t=approved)
time=<YYYYMMDDHHMM>	Point in time to query (e.g., time=202406011330)

Practical Examples

Reproduce a past delivery:

// Find all assets as they were for the Q2 delivery
std::string delivery_time = "202406302359";  // June 30, 2024 23:59

for (const auto& item : space->getItems()) {
    auto rev = item->getRevisionByTagAndTime("published", delivery_time);
    if (rev) {
        std::cout << item->getName() << ": r" << rev->getRevisionNumber() << std::endl;
        for (const auto& artifact : rev->getArtifacts()) {
            std::cout << "  -> " << artifact->getLocation() << std::endl;
        }
    }
}

Compare current vs historical:

// What changed between two milestones?
auto alpha_rev = item->getRevisionByTagAndTime("published", "202403010000");
auto beta_rev = item->getRevisionByTagAndTime("published", "202406010000");

if (alpha_rev && beta_rev && alpha_rev->getRevisionNumber() != beta_rev->getRevisionNumber()) {
    std::cout << "Asset changed from r" << alpha_rev->getRevisionNumber() 
              << " to r" << beta_rev->getRevisionNumber() << std::endl;
}

Tags and Time

The published tag is especially important for time-based queries because:

1. Immutability: Published revisions cannot be modified or deleted

2. Stability: Downstream consumers can rely on published revisions not changing

3. Audit trail: Tag history is preserved, so you can query what was published when

Common tags for time-based queries:

• published: Approved for downstream consumption

• approved: Supervisor-approved revisions

• delivered: Revisions sent to clients

• milestone-alpha, milestone-beta: Project milestone snapshots

Tenant Usage

// Check tenant resource usage
auto usage = client->getTenantUsage();

std::cout << "Nodes: " << usage.node_count << "/" << usage.node_limit << std::endl;
std::cout << "Usage: " << usage.usagePercent() << "%" << std::endl;

if (usage.isNearLimit()) {
    std::cout << "Warning: Approaching node limit!" << std::endl;
}

Discovery & Auto-Configuration

#include <kumiho/discovery.hpp>
#include <kumiho/token_loader.hpp>

// Auto-discover endpoint from Firebase token
auto firebaseToken = loadFirebaseToken();  // From env or file
if (firebaseToken) {
    auto client = clientFromDiscovery(*firebaseToken);
    // Client is now configured for the correct region
}

// Or load bearer token directly
auto bearerToken = loadBearerToken();  // From KUMIHO_AUTH_TOKEN env

API Reference

Client

Method	Description
createProject(name, description)	Create a new project
getProjects()	List all projects
getProject(name)	Get project by name
deleteProject(id, force)	Delete a project
getRevision(kref)	Get revision by Kref
getItem(kref)	Get item by Kref
resolveKref(kref, tag, time)	Resolve Kref with optional tag/time
resolve(kref)	Resolve Kref to artifact location
getTenantUsage()	Get tenant usage stats
subscribeEvents(project, callback)	Subscribe to events

Project

Method	Description
createSpace(name)	Create a child space
getSpace(path)	Get space by path
getSpaces(recursive)	List spaces
createBundle(name)	Create a bundle
setPublic(allow)	Set public access
update(description)	Update project
delete(force)	Delete project

Space

Method	Description
createSpace(name)	Create nested space
createItem(name, kind)	Create an item
getItems()	List items
getItem(name, kind)	Get item

Item

Method	Description
createRevision(metadata)	Create new revision
getRevisions()	List all revisions
getRevision(number)	Get revision by number
getRevisionByTag(tag)	Get revision by tag
getRevisionByTime(time)	Get revision by timestamp (YYYYMMDDHHMM)
getRevisionByTagAndTime(tag, time)	Get revision by tag and timestamp
getLatestRevision()	Get latest revision
peekNextRevision()	Peek at next revision number

Revision

Method	Description
createArtifact(name, path, meta)	Add artifact
getArtifacts()	List artifacts
createEdge(target, type)	Create edge
getEdges(direction)	Get edges
addTag(tag)	Add tag
removeTag(tag)	Remove tag
updateMetadata(meta)	Update metadata
getAllDependencies(...)	Traverse dependencies
analyzeImpact(...)	Impact analysis

Building from Source

Windows (Visual Studio 2022)

# Recommended (build + run ctest)
$env:VCPKG_ROOT = "C:\\vcpkg"
./scripts/build_and_ctest.ps1 -Config Release

# Or manual:
cmake -B build -G "Visual Studio 17 2022" -A x64 `
    -DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure

Linux/macOS

# Configure
cmake -B build \
    -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \
    -DCMAKE_BUILD_TYPE=Release

# Build
cmake --build build

# Run tests
cd build && ctest --output-on-failure

Running Integration Tests

# Enable integration tests
export KUMIHO_INTEGRATION_TEST=1
export KUMIHO_SERVER_URL=localhost:50051

# Run all tests
ctest --output-on-failure

# Run specific test suite
./kumiho_integration_tests

Authentication (C++ SDK)

Token resolution order:

1. KUMIHO_AUTH_TOKEN env var

2. ~/.kumiho/kumiho_authentication.json (or USERPROFILE%\.kumiho\kumiho_authentication.json on Windows)

You can override the config directory with KUMIHO_CONFIG_DIR.

Project Structure

kumiho-cpp/
├── include/kumiho/       # Public headers
│   ├── kumiho.hpp        # Main include
│   ├── client.hpp        # Client class
│   ├── project.hpp       # Project class
│   ├── space.hpp         # Space class (formerly group.hpp)
│   ├── item.hpp          # Item class (formerly product.hpp)
│   ├── revision.hpp      # Revision class (formerly version.hpp)
│   ├── artifact.hpp      # Artifact class (formerly resource.hpp)
│   ├── edge.hpp          # Edge class (formerly link.hpp)
│   ├── bundle.hpp        # Bundle class (formerly collection.hpp)
│   ├── kref.hpp          # Kref URI handling
│   ├── event.hpp         # Event streaming
│   ├── discovery.hpp     # Auto-discovery
│   ├── token_loader.hpp  # Token utilities
│   ├── types.hpp         # Common types
│   ├── base.hpp          # Base classes
│   └── error.hpp         # Exception types
├── src/                  # Implementation
├── tests/                # Unit tests
│   └── integration/      # Integration tests
├── proto/                # Protobuf definitions
├── docs/                 # Documentation
├── CMakeLists.txt        # Build configuration
└── vcpkg.json           # vcpkg manifest

Environment Variables

Variable	Description
KUMIHO_AUTH_TOKEN	Bearer token for authentication
KUMIHO_FIREBASE_ID_TOKEN	Firebase ID token
KUMIHO_CONTROL_PLANE_URL	Control plane URL override
KUMIHO_USE_CONTROL_PLANE_TOKEN	Use control plane token
KUMIHO_CONFIG_DIR	Config directory override
KUMIHO_INTEGRATION_TEST	Enable integration tests
KUMIHO_SERVER_URL	Server URL for tests

Error Handling

#include <kumiho/error.hpp>

try {
    auto project = client->getProject("non-existent");
} catch (const NotFoundError& e) {
    std::cerr << "Project not found: " << e.what() << std::endl;
} catch (const AuthenticationError& e) {
    std::cerr << "Auth failed: " << e.what() << std::endl;
} catch (const KumihoError& e) {
    std::cerr << "Kumiho error: " << e.what() << std::endl;
}

License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

Links

• Kumiho Clouds

• API Documentation

• Python SDK

• Issue Tracker