productive

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 33 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// BaseURL is Productive.io's API v2 base URL, used unless the "region"
	// configuration field overrides it.
	BaseURL = "https://api.productive.io/api/v2"

	// AuthTokenHeader carries the Productive.io API token on every request.
	AuthTokenHeader = "X-Auth-Token"

	// OrganizationIDHeader scopes every request to one Productive.io
	// organization. Productive.io issues tokens per person, not per
	// organization, so this header is required on every call.
	OrganizationIDHeader = "X-Organization-Id"

	// TaskPayloadType is the payload type the onTask trigger emits.
	TaskPayloadType = "productive.task"

	// ResourceTypeProject is the resource type projects are listed and picked
	// as, both for the onTask trigger's project field and ListResources.
	ResourceTypeProject = "project"

	// ResourceTypeTaskList is a task list inside one project. ListResources
	// requires a "project" parameter with that project's id.
	ResourceTypeTaskList = "task_list"

	// TaskCreatedEvent and TaskUpdatedEvent name the change a task event
	// carries, in the "meta" object of the emitted envelope.
	TaskCreatedEvent = "task.created"
	TaskUpdatedEvent = "task.updated"

	// ActionCreated and ActionUpdated are the values of the onTask trigger's
	// "actions" field.
	ActionCreated = "created"
	ActionUpdated = "updated"

	// WebhookTypeStandard is Productive.io type_id for a normal webhook
	// (not Zapier).
	WebhookTypeStandard = 1

	// EventNewTask and EventUpdatedTask are Productive.io event_id values
	// for task created and task updated.
	EventNewTask     = 1
	EventUpdatedTask = 24

	// TaskTypeRegular is a normal Productive.io task. TaskTypeMilestone is
	// a key task.
	TaskTypeRegular   = 1
	TaskTypeMilestone = 3

	// EventHeader is a custom header SuperPlane asks Productive.io to send.
	// Productive.io does not send it on real deliveries, so the signature
	// token is what tells a created task from an updated task.
	EventHeader = "X-Productive-Event"

	// SignatureHeader carries Productive.io's HMAC of timestamp + "." + body.
	SignatureHeader = "Productive-Signature"
)

Variables

View Source
var ErrMissingWritePermission error = missingWritePermissionError{}

ErrMissingWritePermission reports that the API token can authenticate but cannot create webhooks. Error returns the message shown to the user.

View Source
var ErrWebhooksLimitExceeded = errors.New("productive.io plan does not include webhooks")

ErrWebhooksLimitExceeded reports that Productive.io rejected a webhook registration because the organization's plan does not include webhooks.

Functions

func IsNotFoundError

func IsNotFoundError(err error) bool

func IsProductiveFileURL

func IsProductiveFileURL(raw string) bool

IsProductiveFileURL reports whether raw points at a Productive.io file download. API resources under /api/v2/attachments are not file downloads.

func LockTaskWorkOrder

func LockTaskWorkOrder(tx *gorm.DB, factory *models.Factory, ref TaskRef) error

LockTaskWorkOrder serializes work-order creation for one Productive.io task in this factory. The lock is held until the caller commits tx.

func StatusCode

func StatusCode(err error) (int, bool)

func StatusError

func StatusError(statusCode int) error

func TaskEnvelope

func TaskEnvelope(event string, document map[string]any, organizationID string) map[string]any

TaskEnvelope wraps a task resource the way every consumer of this trigger reads it: the JSON:API resource under "data", the change that produced it under "meta", and the Productive.io task page under "url" when the organization id is known. Seeded tasks use the same shape, so nothing downstream can tell a seeded task from a polled one.

func TaskHasWorkOrder

func TaskHasWorkOrder(tx *gorm.DB, factory *models.Factory, ref TaskRef) (bool, error)

TaskHasWorkOrder reports whether this factory already has a work order for this Productive.io task. Matching covers every work-order state, both by origin URL and by an origin-less work order whose source run is this task (webhook bodies used to omit the page URL).

func TaskIDFromEventData

func TaskIDFromEventData(eventData any) (string, bool)

TaskIDFromEventData reads the Productive.io task id from a canvas root event. The envelope looks like:

{ "type": "productive.task", "data": { "data": { "id": "20305431" } } }

func TaskIDFromURL

func TaskIDFromURL(rawURL string) (string, bool)

TaskIDFromURL reads the Productive.io task id from a task page URL.

func TaskURL

func TaskURL(organizationID, taskID string) string

TaskURL is the Productive.io page for one task. Work orders store this as origin so a later update of the same task does not create another one.

func TaskURLFragment

func TaskURLFragment(taskID string) string

TaskURLFragment is the origin-URL substring that identifies a Productive.io task. Callers use it for a coarse lookup, then confirm with TaskIDFromURL so `/tasks/9` cannot match `/tasks/91`.

Types

type Attachment

type Attachment struct {
	Name        string
	ContentType string
	URL         string
}

Attachment is a file linked to a Productive.io task. The webhook payload does not include these records. They come from GET /attachments.

type Client

type Client struct {
	APIToken       string
	OrganizationID string
	BaseURL        string
	// contains filtered or unexported fields
}

Client talks to Productive.io's JSON:API v2 API using an API token and an organization id, both sent as headers on every request.

func NewClient

func NewClient(httpCtx core.HTTPContext, ctx core.IntegrationContext) (*Client, error)

func (*Client) CreateWebhook

func (c *Client) CreateWebhook(webhookURL string, eventID int, eventName string) (*Webhook, error)

CreateWebhook registers an organization webhook that POSTs eventID deliveries to webhookURL. eventName is sent back on each delivery as EventHeader. Productive.io answers 403 webhooks_limit_exceeded (surfaced as ErrWebhooksLimitExceeded) on plans that do not include webhooks.

func (*Client) DeleteWebhook

func (c *Client) DeleteWebhook(id string) error

DeleteWebhook removes a webhook by its Productive.io resource id.

func (*Client) GetProject

func (c *Client) GetProject(id string) (*Project, error)

GetProject fetches a single project by id, for resolving the project a trigger was configured with into the name shown on its canvas card.

func (*Client) GetTask

func (c *Client) GetTask(id string) (*Task, error)

GetTask returns one task by its Productive.io resource id.

func (*Client) ListNewestOpenTaskDocuments

func (c *Client) ListNewestOpenTaskDocuments(projectID string, limit int, regularOnly bool, taskListIDs []string) ([]map[string]any, error)

ListNewestOpenTaskDocuments returns the untrimmed JSON:API resource of each open task in the project, newest first. Seeding an intake replays these through the graph the trigger feeds, and that graph reads attributes Task does not keep.

func (*Client) ListProjects

func (c *Client) ListProjects() ([]Project, error)

ListProjects returns every project of the organization. Productive.io paginates responses, so pages are walked until a short page ends them.

func (*Client) ListTaskAttachments

func (c *Client) ListTaskAttachments(taskID string) ([]Attachment, error)

ListTaskAttachments returns files linked to one task. Deleted rows are omitted.

func (*Client) ListTaskLists

func (c *Client) ListTaskLists(projectID string) ([]TaskList, error)

ListTaskLists returns the active task lists of one project. Productive.io paginates responses, so pages are walked until a short page ends them.

func (*Client) ListTasks

func (c *Client) ListTasks(projectID, query string, limit int, regularOnly bool, taskListIDs []string) ([]Task, error)

ListTasks returns open tasks from one project, optionally filtered by text. When regularOnly is set, key tasks (milestones) are omitted. A non-empty taskListIDs keeps tasks that belong to those task lists.

func (*Client) TaskFiles

func (c *Client) TaskFiles(ctx context.Context, taskID, description string) ([]TaskFile, error)

TaskFiles downloads the files attached to a task, plus Productive.io file URLs already written in description. The API token is added only on the download request. It is not returned.

func (*Client) ValidateCredentials

func (c *Client) ValidateCredentials() error

ValidateCredentials confirms the token and organization id are accepted by Productive.io. Organization memberships is the cheapest authenticated endpoint that also proves the organization id header is correct: a token valid for a different organization is rejected before any data is read.

func (*Client) ValidateWebhookPermission

func (c *Client) ValidateWebhookPermission() error

ValidateWebhookPermission confirms the token can create webhooks.

The probe posts a webhook with empty attributes. Productive rejects that body when the token can write, and rejects the request earlier when it cannot. A webhook that is created anyway is deleted before this returns.

type NodeMetadata

type NodeMetadata struct {
	Project *Project `json:"project,omitempty" mapstructure:"project,omitempty"`
}

NodeMetadata is stored on productive.onTask nodes, so canvas cards can show the project without re-querying Productive.io.

type OnTask

type OnTask struct{}

func (*OnTask) Cleanup

func (t *OnTask) Cleanup(ctx core.TriggerContext) error

func (*OnTask) Color

func (t *OnTask) Color() string

func (*OnTask) Configuration

func (t *OnTask) Configuration() []configuration.Field

func (*OnTask) Description

func (t *OnTask) Description() string

func (*OnTask) Documentation

func (t *OnTask) Documentation() string

func (*OnTask) ExampleData

func (t *OnTask) ExampleData() map[string]any

func (*OnTask) HandleHook

func (t *OnTask) HandleHook(ctx core.TriggerHookContext) (map[string]any, error)

func (*OnTask) HandleWebhook

func (t *OnTask) HandleWebhook(ctx core.WebhookRequestContext) (int, *core.WebhookResponseBody, error)

HandleWebhook emits the productive.task envelope for a task.created or task.updated delivery, filtered to the actions this node was configured to listen for.

func (*OnTask) Hooks

func (t *OnTask) Hooks() []core.Hook

func (*OnTask) Icon

func (t *OnTask) Icon() string

func (*OnTask) Label

func (t *OnTask) Label() string

func (*OnTask) Name

func (t *OnTask) Name() string

func (*OnTask) Setup

func (t *OnTask) Setup(ctx core.TriggerContext) error

type OnTaskConfiguration

type OnTaskConfiguration struct {
	Project string   `json:"project" mapstructure:"project"`
	Actions []string `json:"actions" mapstructure:"actions"`
}

type Productive

type Productive struct{}

func (*Productive) Actions

func (p *Productive) Actions() []core.Action

func (*Productive) Cleanup

func (*Productive) Configuration

func (p *Productive) Configuration() []configuration.Field

func (*Productive) Description

func (p *Productive) Description() string

func (*Productive) HandleHook

func (p *Productive) HandleHook(ctx core.IntegrationHookContext) error

func (*Productive) HandleRequest

func (p *Productive) HandleRequest(ctx core.HTTPRequestContext)

func (*Productive) Hooks

func (p *Productive) Hooks() []core.Hook

func (*Productive) Icon

func (p *Productive) Icon() string

func (*Productive) Instructions

func (p *Productive) Instructions() string

func (*Productive) Label

func (p *Productive) Label() string

func (*Productive) ListResources

func (p *Productive) ListResources(resourceType string, ctx core.ListResourcesContext) ([]core.IntegrationResource, error)

func (*Productive) Name

func (p *Productive) Name() string

func (*Productive) Sync

func (p *Productive) Sync(ctx core.SyncContext) error

func (*Productive) Triggers

func (p *Productive) Triggers() []core.Trigger

type ProductiveWebhookHandler

type ProductiveWebhookHandler struct{}

ProductiveWebhookHandler creates and tears down the Productive.io webhooks the onTask trigger subscribes to.

func (*ProductiveWebhookHandler) Cleanup

func (*ProductiveWebhookHandler) CompareConfig

func (h *ProductiveWebhookHandler) CompareConfig(a, b any) (bool, error)

func (*ProductiveWebhookHandler) Merge

func (h *ProductiveWebhookHandler) Merge(current, requested any) (any, bool, error)

func (*ProductiveWebhookHandler) Setup

type Project

type Project struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

Project is a Productive.io project, used by the onTask trigger's project picker and to scope a webhook to one project.

type Task

type Task struct {
	ID          string
	Number      string
	Title       string
	Description string
	ProjectID   string
	TaskListID  string
	Closed      bool
	TypeID      int
}

Task is a Productive.io task that can seed a factory intake.

func (Task) IsKeyTask

func (t Task) IsKeyTask() bool

type TaskFile

type TaskFile struct {
	Name        string
	ContentType string
	Body        []byte
	ReplaceURLs []string
}

TaskFile is a downloaded Productive.io file ready to store on a work order. ReplaceURLs are the exact description strings that should become the stored file reference. An empty list means the file is appended.

type TaskList

type TaskList struct {
	ID   string
	Name string
}

TaskList is a Productive.io task list inside one project.

type TaskListMove

type TaskListMove struct {
	From string
	To   string
}

TaskListMove is a Productive.io task changing task lists. From and To are task list ids. An empty From means the task had no list.

type TaskRef

type TaskRef struct {
	OrganizationID string
	TaskID         string
}

TaskRef identifies one Productive.io task in one Productive organization. Task ids are unique inside an organization, not across organizations.

func TaskRefFromEventData

func TaskRefFromEventData(eventData any) (TaskRef, bool)

TaskRefFromEventData reads the Productive.io task id and organization from a canvas root event. The organization comes from the task page URL. Older events omit that URL, so OrganizationID can be empty.

func TaskRefFromURL

func TaskRefFromURL(rawURL string) (TaskRef, bool)

TaskRefFromURL reads the Productive.io organization and task id from a task page URL.

type Webhook

type Webhook struct {
	ID             string
	SignatureToken string
}

Webhook is a Productive.io webhook subscription. Productive.io webhooks are organization-wide and fire for one event_id each.

type WebhookConfiguration

type WebhookConfiguration struct {
	ProjectID string `json:"projectId" mapstructure:"projectId"`
}

WebhookConfiguration scopes a SuperPlane webhook to one Productive.io project. Remote webhooks are organization-wide; the project id is used to share one SuperPlane webhook among nodes and to filter deliveries.

type WebhookMetadata

type WebhookMetadata struct {
	IDs []string `json:"ids" mapstructure:"ids"`
	// ID is the single remote id the invented API stored. Cleanup still
	// deletes it so an old record does not leak a Productive.io webhook.
	ID string `json:"id,omitempty" mapstructure:"id,omitempty"`
}

WebhookMetadata is stored on the webhook record after remote webhooks are created, so Cleanup can delete each Productive.io webhook again.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL