organization.proto

syntax = "proto3";

package hiber.organization;

import "base.proto";
import "file.proto";
import "value.proto";

option java_multiple_files = false;
option java_package = "global.hiber.api.grpc.organization";
option java_outer_classname = "OrganizationApi";
option go_package = ".;hiber";

/* Organization-related api calls. Currently limited to your own organization; we'll add more for creating and managing
 * sub-organizations later.
 */
service OrganizationService {
    rpc Create (CreateOrganizationRequest) returns (Organization);
    rpc Get (GetOrganizationRequest) returns (Organization);
    rpc Update (UpdateOrganizationRequest) returns (Organization);
    rpc Delete (DeleteOrganizationRequest) returns (DeleteOrganizationRequest.Response);
    rpc Tree (OrganizationTreeRequest) returns (OrganizationTreeRequest.Response);
    rpc ListChildOrganizations (ListChildOrganizationsRequest) returns (ListChildOrganizationsRequest.Response);
    rpc ValidateCreationToken (ValidateOrganizationCreationTokenRequest) returns (ValidateOrganizationCreationTokenRequest.Response);
    rpc GetAvatar (GetOrganizationAvatar.Request) returns (GetOrganizationAvatar.Response);
}

/* Organization data. An Organization can have many linked users, but the organization is the owner
 * of any modems and related data.
 */
message Organization {
    /* An avatar is represented either by a (publicly) fetchable URL that serves an image,
     * xor a binary payload that knows its name and mime-type.
     *
     * If it is a url, it must be obtainable without credentials, though this is not validated by the API.
     * Because the content behind URL's can change or become unavailable over time,
     * the client should make sure it properly caches the data fetched from the URL.
     * ("Properly" means [among other things] respecting the response headers for this resource)
     */
    message Avatar {
        oneof url_or_image {
            /* A URL that contains the location of avatar. */
            string url = 1;

            /* The data of the avatar as a Named File. */
            file.File image = 2;
        }
    }

    message Address {
        repeated string lines = 1;
        string zip_code = 2;
        string city = 3;
        string state = 4;
        string country = 5;
    }

    message Contact {
        string name = 1;
        string email = 2;
        string phone = 3;
    }
    /* Default settings for this organization. */
    message Defaults {
        /* The default expected transmission interval for devices in this organization.  */
        optional hiber.value.Value.Numeric.Rate expected_device_transmission_rate = 1;
    }

    enum Feature {
        UNKNOWN = 0;

        /* Required to manually create modems using the ModemService. */
        MODEM_CREATION = 4;

        /* Used for organizations that get early access to features. */
        EARLY_ACCESS = 5;

        /* Used for organizations that get access to experimental features. e.g. feature work in progress. */
        EXPERIMENTAL = 6;

        /* Access the list of assets in Mission Control. */
        ASSETS = 10;

        /* Use the new assets as primary data owner in Mission Control dashboards. */
        ASSET_DASHBOARD = 11;

        /* Display and use device and gateway locations in Mission Control. */
        LOCATIONS = 12;

        reserved 1, 2, 3, 7, 8, 9;
    }

    /* The slug for this organization, used to identify organizations */
    string organization = 1;
    /* The name of the organization to display to the end-user */
    string display_name = 2;

    Address address = 4;
    Contact contact = 7;

    string vat_number = 3;
    string billing_name = 5;
    Address billing_address = 6;

    Timestamp contract_signature_date = 8;
    Timestamp created_at = 9;
    Timestamp updated_at = 10;

    repeated Feature features = 11;

    string database_info = 12;

    optional Defaults defaults = 13;

}

/* Selection object for child organizations.
 * User for child organization list and tree.
 */
message OrganizationSelection {
    optional Filter.Organizations organizations = 1;
    optional string search = 2;
}

/* Get your current organization's data
 */
message GetOrganizationRequest {
    /* Pick the organization to get the details for. If unset, your default organization is used. */
    optional string organization = 1;
}

/* Update organization data.
 * All fields are effectively optional, though address, billing_address, contact and features are assumed to be complete objects,
 * not partial updates.
 * Note that the organization field specifies the organization, it is not used to update the current organization identifier.
 */
message UpdateOrganizationRequest {
    optional string organization = 1;
    string display_name = 2;
    string vat_number = 3;
    Organization.Address address = 4;
    string billing_name = 5;
    Organization.Address billing_address = 6;
    Organization.Contact contact = 7;
    Organization.Avatar avatar = 8;
}

/* Get your current organization's organization tree.
 * The organization tree contains your current organization as the root of the tree, with all child organizations ordered below it.
 */
message OrganizationTreeRequest {
    message Response {
        OrganizationTreeRequest request = 1;
        OrganizationTree tree = 2;
    }

    /* Pick the organization to use (/impersonate) for this call, overriding your default organization */
    optional string organization = 1;
    OrganizationSelection selection = 2;
}

message OrganizationTree {
    Organization organization = 1;
    repeated OrganizationTree children = 3;
}

/* List the child organizations for the given organization
 */
message ListChildOrganizationsRequest {
    message Response {
        repeated Organization child_organizations = 1;
        ListChildOrganizationsRequest request = 2;
        Pagination.Result pagination = 3;
    }

    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    optional string organization = 1;

    /* Select the organizations to list. Optional, when omitted or empty everything is included. */
    optional OrganizationSelection selection = 2;
    optional Pagination pagination = 3;
    optional bool include_details = 4;
}

message CreateOrganizationRequest {
    /* Pick the organization to use as parent. If unset, your default organization is used.
     * If you have no organization, an organization_creation_token is required.
     */
    string parent_organization = 1;

    /* The name for the new organization. Lowercase, letters, numbers, dashes and underscores only. Required.
     * Used as an identifier for the organization.
     */
    string new_organization = 2;

    /* The name to display for your organization (i.e. capitalized, with spaces, etc.). Default to the name above. */
    optional string display_name = 3;

    /* The avatar image representing this organization. Usually the logo. */
    optional Organization.Avatar avatar = 11;

    /* Whether this organization is created for a business. */
    optional bool is_business = 4;

    /* Whether this organization is created for a business, provide a VAT number. */
    optional string vat_number = 5;

    /* Postal address for your organization. */
    optional Organization.Address address = 6;

    /* Billing information for your organization. Optional, but required if you want active modems. */
    optional string billing_name = 7;

    /* Billing address for your organization. Optional, but required if you want active modems. */
    optional Organization.Address billing_address = 8;

    /* Contact information for your organization. Required. */
    Organization.Contact contact = 9;

    /* A token that allows you to create an organization without having an organization. */
    optional string organization_creation_token = 10;
}

message DeleteOrganizationRequest {
    message Response {
        string organization_to_delete = 1;

        /* The organizations that were deleted. */
        OrganizationTree organizations_deleted = 3;

        reserved 2;
    }

    /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
    string parent_organization = 1;

    /* The organization to delete. Required. */
    string organization_to_delete = 2;
}

message ValidateOrganizationCreationTokenRequest {
    message Response {
        bool valid = 1;
    }

    /* A token that allows you to create an organization without having an organization. */
    string organization_creation_token = 1;
}

message GetOrganizationAvatar {
    message Request {
        /* The slug for this organization, used to identify organizations */
        repeated string organizations = 1;

        optional Pagination pagination = 2;
    }
    message Response {
        /* Avatars, indexed by organization slug */
        map<string, Organization.Avatar> avatars = 1;

        Pagination.Result pagination = 2;
    }
}