design

Documentation

Overview

Package design declares the Goa API for the dev-idp management surface.

This API is intentionally separate from the production gram API. It lives under the top-level dev-idp/ project so its design and generated code cannot leak into the production binary.

Every method in every service here is unauthenticated. dev-idp is a localhost-only tool.

Index

• Variables
• func PaginationPayload()
• func PaginationResult()

Variables

var CurrentUser = Type("CurrentUser", func() {
	Attribute("mode", String, "Mode whose currentUser is being reported.", func() {
		Enum("mock-workos", "oauth2-1", "oauth2", "workos")
	})
	Attribute("user", User, "Local user record. Populated for mock-workos / oauth2-1 / oauth2.")
	Attribute("workos", WorkosCurrentUser, "Live WorkOS profile. Populated for workos mode only.")

	Required("mode")
})

CurrentUser is the discriminated payload returned by devIdp.getCurrentUser. `mode` tells the consumer which mode was read. Local modes populate `user`; the workos mode populates `workos`.

var Invitation = Type("Invitation", func() {
	Attribute("id", String, "Invitation UUID.", func() {
		Format(FormatUUID)
	})
	Attribute("email", String, "Invitee email address.")
	Attribute("organization_id", String, "Organization UUID.", func() {
		Format(FormatUUID)
	})
	Attribute("state", String, "Invitation lifecycle state.", func() {
		Enum("pending", "accepted", "revoked", "expired")
	})
	Attribute("token", String, "Opaque token used by /findByToken and the accept-flow URL.")
	Attribute("inviter_user_id", String, "User UUID of the inviter, when known.", func() {
		Format(FormatUUID)
	})
	Attribute("accepted_at", String, "Timestamp when the invitation was accepted; empty for pending.", func() {
		Format(FormatDateTime)
	})
	Attribute("revoked_at", String, "Timestamp when the invitation was revoked; empty for pending.", func() {
		Format(FormatDateTime)
	})
	Attribute("expires_at", String, "Timestamp when the invitation expires.", func() {
		Format(FormatDateTime)
	})
	Attribute("created_at", String, func() {
		Format(FormatDateTime)
	})
	Attribute("updated_at", String, func() {
		Format(FormatDateTime)
	})

	Required("id", "email", "organization_id", "state", "token", "expires_at", "created_at", "updated_at")
})

Invitation mirrors the dev-idp `invitations` table. Backs the /rpc/invitations.* surface and the WorkOS-emulation surface under /mock-workos/user_management/invitations*.

var ListInvitationsResult = Type("ListInvitationsResult", func() {
	Attribute("items", ArrayOf(Invitation), "Invitations on this page.")
	PaginationResult()
	Required("items")
})

var ListMembershipsResult = Type("ListMembershipsResult", func() {
	Attribute("items", ArrayOf(Membership), "Memberships on this page.")
	PaginationResult()
	Required("items")
})

var ListOrganizationRolesResult = Type("ListOrganizationRolesResult", func() {
	Attribute("items", ArrayOf(OrganizationRole), "Roles for the organization.")
	Required("items")
})

var ListOrganizationsResult = Type("ListOrganizationsResult", func() {
	Attribute("items", ArrayOf(Organization), "Organizations on this page.")
	PaginationResult()
	Required("items")
})

var ListUsersResult = Type("ListUsersResult", func() {
	Attribute("items", ArrayOf(User), "Users on this page.")
	PaginationResult()
	Required("items")
})

var Membership = Type("Membership", func() {
	Attribute("id", String, "Membership UUID.", func() {
		Format(FormatUUID)
	})
	Attribute("user_id", String, "User UUID.", func() {
		Format(FormatUUID)
	})
	Attribute("organization_id", String, "Organization UUID.", func() {
		Format(FormatUUID)
	})
	Attribute("role", String, "Role within the organization (default `member`).")
	Attribute("created_at", String, func() {
		Format(FormatDateTime)
	})
	Attribute("updated_at", String, func() {
		Format(FormatDateTime)
	})

	Required("id", "user_id", "organization_id", "role", "created_at", "updated_at")
})

Membership mirrors the dev-idp `memberships` table (idp-design.md §5).

var Organization = Type("Organization", func() {
	Attribute("id", String, "Organization UUID.", func() {
		Format(FormatUUID)
	})
	Attribute("name", String, "Display name.")
	Attribute("slug", String, "URL slug (unique).")
	Attribute("account_type", String, "Plan tier (`free`, etc.).")
	Attribute("workos_id", String, "Optional WorkOS organization id.")
	Attribute("created_at", String, func() {
		Format(FormatDateTime)
	})
	Attribute("updated_at", String, func() {
		Format(FormatDateTime)
	})

	Required("id", "name", "slug", "account_type", "created_at", "updated_at")
})

Organization mirrors the dev-idp `organizations` table (idp-design.md §5).

var OrganizationRole = Type("OrganizationRole", func() {
	Attribute("id", String, "Role UUID.", func() {
		Format(FormatUUID)
	})
	Attribute("organization_id", String, "Organization UUID.", func() {
		Format(FormatUUID)
	})
	Attribute("slug", String, "Role slug — unique within the organization.")
	Attribute("name", String, "Display name.")
	Attribute("description", String, "Free-form description; empty string when unset.")
	Attribute("created_at", String, func() {
		Format(FormatDateTime)
	})
	Attribute("updated_at", String, func() {
		Format(FormatDateTime)
	})

	Required("id", "organization_id", "slug", "name", "description", "created_at", "updated_at")
})

OrganizationRole mirrors the dev-idp `organization_roles` table. Surfaced from /rpc/organizationRoles.* and the WorkOS-emulation surface under /mock-workos/authorization/organizations/{id}/roles (idp-design.md §7.1, "WorkOS emulation").

var User = Type("User", func() {
	Attribute("id", String, "User UUID.", func() {
		Format(FormatUUID)
	})
	Attribute("email", String, "Email address (unique).")
	Attribute("display_name", String, "Display name.")
	Attribute("photo_url", String, "Optional photo URL.")
	Attribute("github_handle", String, "Optional GitHub handle.")
	Attribute("admin", Boolean, "Admin flag.")
	Attribute("whitelisted", Boolean, "Whitelist flag.")
	Attribute("created_at", String, func() {
		Format(FormatDateTime)
	})
	Attribute("updated_at", String, func() {
		Format(FormatDateTime)
	})

	Required("id", "email", "display_name", "admin", "whitelisted", "created_at", "updated_at")
})

User mirrors the dev-idp `users` table (idp-design.md §5).

var WorkosCurrentUser = Type("WorkosCurrentUser", func() {
	Attribute("workos_sub", String, "WorkOS user id (the `sub` stored in current_users).")
	Attribute("email", String, "Email address from the live WorkOS user record.")
	Attribute("first_name", String)
	Attribute("last_name", String)
	Attribute("profile_picture_url", String)
	Attribute("organization_id", String, "Default WorkOS organization id, when set.")

	Required("workos_sub")
})

WorkosCurrentUser is the workos-mode payload returned from devIdp.getCurrentUser. The shape mirrors the live WorkOS users.get response (idp-design.md §6.2 / §7.2). Fields beyond `workos_sub` are best-effort — populated when the proxy round-trip succeeds, omitted otherwise.

Functions

func PaginationPayload

func PaginationPayload()

PaginationPayload is mixed into every list-method payload. See idp-design.md §6: cursor + limit, default 50, max 100.

func PaginationResult

func PaginationResult()

PaginationResult is mixed into every list-method result. `next_cursor` is empty when the page exhausts the result set.