resolve

func ClientID ¶ added in v0.4.0

func ClientID(ctx context.Context, client *clockify.Client, workspaceID, ref string) (string, error)

ClientID returns the Clockify client ID for ref, which may be a canonical client ID or a workspace-local client name. Same resolution and error contract as ProjectID.

func ProjectID ¶ added in v0.4.0

func ProjectID(ctx context.Context, client *clockify.Client, workspaceID, ref string) (string, error)

ProjectID returns the Clockify project ID for ref, which may be either a canonical project ID (returned verbatim after validation) or a workspace-local project name (resolved via case-insensitive strict-name search against the workspace's project list). Returns an error when the ref is unknown, ambiguous (multiple matches), or fails ID validation when treated as an ID.

func TagID ¶ added in v0.4.0

func TagID(ctx context.Context, client *clockify.Client, workspaceID, ref string) (string, error)

TagID returns the Clockify tag ID for ref, which may be a canonical tag ID or a workspace-local tag name. Same resolution and error contract as ProjectID.

func TaskID ¶ added in v0.4.0

func TaskID(ctx context.Context, client *clockify.Client, workspaceID, projectID, ref string) (string, error)

TaskID returns the Clockify task ID for ref under the given project. ref may be a canonical task ID or a project-local task name. projectID must already be a validated Clockify project ID (e.g. the result of ProjectID). Same resolution and error contract as ProjectID.

func UserID ¶ added in v0.4.0

func UserID(ctx context.Context, client *clockify.Client, workspaceID, ref string) (string, error)

UserID returns the Clockify user ID for ref. ref may be a canonical user ID (returned verbatim after ValidateID), an email address (matched against the user record's email field with case-insensitive equality), or a display name (matched against the name field with strict-name-search semantics). Email matches use the Clockify "email=" query parameter and name matches use "name=" with strict-name-search=true to avoid prefix collisions. Returns an error when the ref is unknown or ambiguous.

func ValidateID ¶

func ValidateID(id, name string) error

ValidateID checks that id is suitable for use as a path segment in a Clockify request URL. The character class is intentionally narrower than the full Clockify ID surface so a pasted token or key fragment fails before path construction: "/", "?", "#", "%", control bytes, "..", empty/whitespace, and lengths over maxIDLength are rejected. name appears verbatim in the returned error so the caller learns which field was invalid (e.g. "project_id").

func ValidateNameRef ¶

func ValidateNameRef(ref, kind string) error

ValidateNameRef is the permissive sibling of ValidateID, used for name-or-ID inputs that resolve to a Clockify entity by name. Names reach the Clockify API as URL query-parameter values (which url.Values safely percent-encodes) — never as path segments — so the strict path-safety character class ValidateID enforces would over-reject legitimate workspace names like "ACME / Support" or "R&D 50%".

The contract here mirrors the API surface: anything that's not a control byte and isn't pathologically long is accepted; the caller is expected to resolve it via name lookup, then validate the resulting Clockify ID with ValidateID before any path use.