share_space #

{
  "name": "share_space",
  "resource": "account",
  "tier": "reversible",
  "surface": "tztrack",
  "product": "tztrack",
  "admits": [
    "tztrack",
    "device_sign_in"
  ],
  "summary": "Share one issue space the account owns with other accounts, each a member at one level. `space` picks the space. `add` gives an existing account by the email address it signs in with, and `level` the level it works the space at through `relay_issue_act`, `report`, `contribute`, or `owner`, `contribute` where absent; a standing member's level moves. `remove` gives a member by that address. With neither the call is refused `invalid_request`, pointing to `list_space_members`. An address no account signed in with is refused `no_such_account`, and nothing is kept for a later sign-in. A space the account does not own, one shared with it among them, is refused `space_not_owned`; a member never shares, and the feedback actions stay the owner's. An account that does not hold tzTrack is refused `blueprint_required` ahead of the form and the space's ownership. The answer carries the members, each with its account, address, level, and the instant it was added, and `users`, the members plus the owner, and the owner's tzTrack tier and payment grace's end after the call, `tztrack_tier` and `tztrack_grace_end`, so an `add` that starts a grace says so. Registered while the issue service's origin is configured.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}

{
  "name": "share_space",
  "title": "Share issue space",
  "tier": "reversible",
  "scenario": "API-L0-20",
  "summary": "Add or remove a member of an issue space you own; pass `space` and either `add` or `remove`. Use `list_space_members` to read membership without changing it. `add` takes an existing account's sign-in email and a `level` of `report`, `contribute`, or `owner`, defaulting to `contribute`; a repeat changes that member's level. `remove` takes the member's email. An address with no signed-in account is refused `no_such_account`, with nothing kept for later.\n\nA member works the space at its level and cannot share it. The answer lists the members; `users` counts them plus you, and `tztrack_tier` gives your account's tier. Your account needs tzTrack, which every account has.",
  "owners": [
    "ITS-L0-07",
    "ACB-L0-92"
  ]
}

{
  "request": {
    "type": "object",
    "required": [
      "space"
    ],
    "properties": {
      "space": {
        "type": "string",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
        "description": "The space to share, a lower-case UUID of a space your account owns."
      },
      "add": {
        "type": "string",
        "maxLength": 320,
        "description": "The sign-in email address of an existing account to add as a member, or whose level to move. An address no account signed in with is refused `no_such_account`; nothing is kept for a later sign-in. Never beside `remove`."
      },
      "level": {
        "type": "string",
        "enum": [
          "report",
          "contribute",
          "owner"
        ],
        "description": "With `add`: the level the member works the space at through the relay, `contribute` where absent. `owner` reaches every relayed act and makes nobody an owner: the space stays yours, and a member never shares it."
      },
      "remove": {
        "type": "string",
        "maxLength": 320,
        "description": "The sign-in email address of the member to remove. Never beside `add`."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "space",
      "members",
      "users",
      "tztrack_tier",
      "tztrack_grace_end"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call's record row. Quote it when you report the call."
      },
      "space": {
        "type": "string",
        "description": "The space shared."
      },
      "members": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "account",
            "address",
            "level",
            "added_at"
          ],
          "properties": {
            "account": {
              "type": "string",
              "description": "The member's account identifier, the one its claims and its `person:<account>` carry."
            },
            "address": {
              "type": "string",
              "description": "The sign-in email address the member was added by."
            },
            "level": {
              "type": "string",
              "enum": [
                "report",
                "contribute",
                "owner"
              ]
            },
            "added_at": {
              "type": "string",
              "description": "The instant the member was added, or its level last moved."
            }
          }
        },
        "description": "The members of the space after the call, oldest first; you, the owner, are not among them."
      },
      "users": {
        "type": "integer",
        "minimum": 1,
        "description": "The members plus you."
      },
      "tztrack_tier": {
        "type": "string",
        "enum": [
          "introductory",
          "paid",
          "grace",
          "stopped",
          "free"
        ],
        "description": "Your account's tzTrack tier as the space's owner, after the call (ACB-L0-92). It is derived at the read, so an `add` that starts a payment grace says so. It is `introductory` while tzTrack's introductory period runs; after it, `paid`, `grace` for an account that must pay inside its payment grace, `stopped` once that grace has ended, or `free`."
      },
      "tztrack_grace_end": {
        "type": [
          "string",
          "null"
        ],
        "description": "The end of your account's, the owner's, tzTrack payment grace, ISO 8601, where one was written, and null otherwise (ACB-L0-92). Past it, an account that must pay and reads no paid tier reads `stopped`."
      }
    }
  }
}