puter.threads

The puter.threads module provides functionality for creating, managing, and interacting with thread objects. Threads are identified by UUIDs and can be organized hierarchically with parent-child relationships.

Overview

Threads provide a flexible way to create nested conversations or content structures. They can be used for:

  • Comment systems
  • Discussion forums
  • Nested content organization
  • Real-time collaborative features

Each thread:

  • Has a unique UUID
  • Can have a parent thread (optional)
  • Can have multiple child threads
  • Supports subscription to various events
  • Has permission-based access controls

Methods

puter.threads.create

Creates a new thread, either as a root thread or as a child of an existing thread.

Syntax 

puter.threads.create(options);

Parameters

options (object) (required)

An object containing the following properties:

  • content (any) (required): The content to store in the thread.
  • parent_uuid (string) (optional): The UUID of the parent thread. If not provided, a root thread is created.

Return value

An object containing information about the created thread:

{
  uuid: string,       // The UUID of the created thread
  content: any,       // The content stored in the thread
  parent_uuid: string // The UUID of the parent thread (if applicable)
}

Permissions Required

To create a child thread, the current actor needs the thread:UUID-OF-PARENT:post permission. Root threads can be created without special permissions.

Example 

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        // Create a root thread
        puter.threads.create({ content: "This is a root thread" })
            .then(rootThread => {
                console.log("Root thread created:", rootThread);
                
                // Create a child thread
                return puter.threads.create({ 
                    content: "This is a child thread", 
                    parent_uuid: rootThread.uuid 
                });
            })
            .then(childThread => {
                console.log("Child thread created:", childThread);
            })
            .catch(error => {
                console.error("Error creating threads:", error);
            });
    </script>
</body>
</html>

puter.threads.get

Retrieves information about a specific thread.

Syntax 

puter.threads.get(uuid);

Parameters

uuid (string) (required)

The UUID of the thread to retrieve.

Return value

An object containing information about the requested thread:

{
  uuid: string,       // The UUID of the thread
  content: any,       // The content stored in the thread
  parent_uuid: string // The UUID of the parent thread (if applicable)
}

Permissions Required

The current actor needs the thread:UUID-OF-THREAD:read permission to read the contents of the thread, unless they are the owner.

Example 

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        puter.threads.get('550e8400-e29b-41d4-a716-446655440000')
            .then(thread => {
                console.log("Thread retrieved:", thread);
            })
            .catch(error => {
                console.error("Error retrieving thread:", error);
            });
    </script>
</body>
</html>

puter.threads.edit

Updates the content of an existing thread.

Syntax 

puter.threads.edit(uuid, content);

Parameters

uuid (string) (required)

The UUID of the thread to edit.

content (any) (required)

The new content to store in the thread.

Return value

An object containing information about the updated thread:

{
  uuid: string,       // The UUID of the thread
  content: any,       // The updated content stored in the thread
  parent_uuid: string // The UUID of the parent thread (if applicable)
}

Permissions Required

The current actor needs the thread:UUID-OF-THREAD:edit permission to edit the thread, unless they are the owner.

Example 

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        puter.threads.edit('550e8400-e29b-41d4-a716-446655440000', "Updated thread content")
            .then(updatedThread => {
                console.log("Thread updated:", updatedThread);
            })
            .catch(error => {
                console.error("Error updating thread:", error);
            });
    </script>
</body>
</html>

puter.threads.delete

Deletes a thread and optionally its child threads.

Syntax 

puter.threads.delete(uuid, options);

Parameters

uuid (string) (required)

The UUID of the thread to delete.

options (object) (optional)

An object containing the following properties:

  • recursive (boolean) (optional): If set to true, deletes all child threads recursively. Default is false.

Return value

An empty object (reserved for future use).

Permissions Required

The current actor needs the thread:UUID-OF-THREAD:delete permission to delete the thread, unless they are the owner.

To delete child threads recursively, the actor needs either:

  • thread:UUID-OF-THREAD:children-of:delete permission (to delete any child thread)
  • thread:UUID-OF-THREAD:own-children-of:delete permission (to delete only child threads they own)

Example 

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        // Delete a single thread
        puter.threads.delete('550e8400-e29b-41d4-a716-446655440000')
            .then(() => {
                console.log("Thread deleted successfully");
            })
            .catch(error => {
                console.error("Error deleting thread:", error);
            });
            
        // Delete a thread and all its children
        puter.threads.delete('550e8400-e29b-41d4-a716-446655440000', { recursive: true })
            .then(() => {
                console.log("Thread and all children deleted successfully");
            })
            .catch(error => {
                console.error("Error deleting thread hierarchy:", error);
            });
    </script>
</body>
</html>

puter.threads.list

Lists all child threads of a given parent thread.

Syntax 

puter.threads.list(parent_uuid, options);

Parameters

parent_uuid (string) (required)

The UUID of the parent thread whose children should be listed.

options (object) (optional)

An object containing the following properties:

  • limit (number) (optional): Maximum number of threads to return. Default is server-defined.
  • offset (number) (optional): Number of threads to skip. Used for pagination. Default is 0.

Return value

An array of objects, each containing information about a child thread:

[
  {
    uuid: string,       // The UUID of the child thread
    content: any,       // The content stored in the child thread
    parent_uuid: string // The UUID of the parent thread
  },
  // ...more thread objects
]

Permissions Required

The current actor needs the thread:UUID-OF-PARENT:list permission to list child threads, unless they are the owner.

Example 

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        puter.threads.list('550e8400-e29b-41d4-a716-446655440000', { limit: 10 })
            .then(childThreads => {
                console.log("Child threads:", childThreads);
            })
            .catch(error => {
                console.error("Error listing threads:", error);
            });
    </script>
</body>
</html>

puter.threads.subscribe

Subscribes to events on a specific thread.

Syntax 

puter.threads.subscribe(uuid, options, callback);

Parameters

uuid (string) (required)

The UUID of the thread to subscribe to.

options (object) (optional)

An object containing subscription options:

  • events (array) (optional): Array of event names to subscribe to. Default is all events. Possible events:
    • post: Emitted when a child thread is added
    • edit: Emitted when this thread is edited
    • delete: Emitted when this thread is deleted
    • child-edit: Emitted when a direct child thread is edited
    • child-delete: Emitted when a direct child thread is deleted
callback (function) (required)

Function to be called when a subscribed event occurs. The callback receives an event object:

{
  type: string,        // The type of event ('post', 'edit', 'delete', 'child-edit', 'child-delete')
  thread: {            // The thread that triggered the event
    uuid: string,      // The UUID of the thread
    content: any,      // The content of the thread
    parent_uuid: string // The UUID of the parent thread (if applicable)
  }
}

Return value

A subscription object with methods:

{
  unsubscribe: function // Call this function to stop receiving events
}

Permissions Required

The current actor needs the appropriate read permissions for the thread to subscribe to its events.

Example 

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        // Subscribe to all events on a thread
        const subscription = puter.threads.subscribe(
            '550e8400-e29b-41d4-a716-446655440000',
            { events: ['post', 'edit', 'delete', 'child-edit', 'child-delete'] },
            function(event) {
                console.log("Event received:", event.type);
                console.log("Thread data:", event.thread);
            }
        );
    </script>
</body>
</html>

Permissions

Thread operations are controlled by the following permissions:

Permission Description
thread:UUID:post Allows adding child threads to the specified thread
thread:UUID:list Allows listing child threads of the specified thread
thread:UUID:read Allows reading the contents of the specified thread
thread:UUID:edit Allows editing the contents of the specified thread
thread:UUID:delete Allows deleting the specified thread
thread:UUID:children-of:delete Allows deleting any child thread of the specified thread
thread:UUID:own-children-of:delete Allows deleting any child thread of the specified thread that is owned by the current actor
thread:UUID:children-of:edit Allows editing any child thread of the specified thread
thread:UUID:own-children-of:edit Allows editing any child thread of the specified thread that is owned by the current actor

Note: Thread owners automatically have all permissions for their own threads.

PREVIOUS

revokeOrigin()

NEXT

create()