@foir/sdk 0.11.0 → 0.13.0

package/dist/app/contract/proto/apps/v1/apps_pb.d.ts

@@ -0,0 +1,1465 @@
+// @generated by protoc-gen-es v2.12.1 with parameter "import_extension=js"
+// @generated from file apps/v1/apps.proto (package apps.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenEnum, GenExtension, GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { JsonObject, Message } from "@bufbuild/protobuf";
+import type { EnumValueOptions } from "@bufbuild/protobuf/wkt";
+
+/**
+ * Describes the file apps/v1/apps.proto.
+ */
+export declare const file_apps_v1_apps: GenFile;
+
+/**
+ * Top-level manifest.
+ *
+ * @generated from message apps.v1.AppConfig
+ */
+export declare type AppConfig = Message<"apps.v1.AppConfig"> & {
+  /**
+   * REQUIRED. Kebab-case globally unique within a project. Matches the key
+   * under apps.<name> in foir.config.ts.
+   *
+   * @generated from field: string name = 1;
+   */
+  name: string;
+
+  /**
+   * REQUIRED. Semver-like free-text version string. Used only for display
+   * and update-diff context; not interpreted by the platform for ordering.
+   *
+   * @generated from field: string version = 2;
+   */
+  version: string;
+
+  /**
+   * OPTIONAL. Display metadata for admin UI.
+   *
+   * @generated from field: apps.v1.Metadata metadata = 3;
+   */
+  metadata?: Metadata | undefined;
+
+  /**
+   * OPTIONAL. If present, the app has a runtime service. Absent for pure
+   * iframe-only apps.
+   *
+   * @generated from field: apps.v1.Middleware middleware = 4;
+   */
+  middleware?: Middleware | undefined;
+
+  /**
+   * OPTIONAL. Credential strategy and schema. Absent for apps that need no
+   * external-service credentials (CSV importer, color picker).
+   *
+   * @generated from field: apps.v1.Credentials credentials = 5;
+   */
+  credentials?: Credentials | undefined;
+
+  /**
+   * OPTIONAL. JSON Schema describing per-project settings. Shape, not values.
+   *
+   * @generated from field: google.protobuf.Struct settings_schema = 6;
+   */
+  settingsSchema?: JsonObject | undefined;
+
+  /**
+   * OPTIONAL. Inbound data shapes the app can deliver. Each source type is
+   * mapped onto a project model at install time.
+   *
+   * @generated from field: map<string, apps.v1.SourceType> sources = 7;
+   */
+  sources: { [key: string]: SourceType };
+
+  /**
+   * OPTIONAL. Outbound data requirements. Each sink is mapped onto a
+   * project model at install time.
+   *
+   * @generated from field: map<string, apps.v1.SinkContract> sinks = 8;
+   */
+  sinks: { [key: string]: SinkContract };
+
+  /**
+   * OPTIONAL. Operations contributed by the app. Keys starting with `__`
+   * are platform-reserved (__uninstall, __validate_credentials).
+   *
+   * @generated from field: repeated apps.v1.Operation operations = 9;
+   */
+  operations: Operation[];
+
+  /**
+   * OPTIONAL. Hooks contributed by the app. Filters use source-type or
+   * sink-contract names; platform resolves to mapped model keys at install.
+   *
+   * @generated from field: repeated apps.v1.Hook hooks = 10;
+   */
+  hooks: Hook[];
+
+  /**
+   * OPTIONAL. UI placements the app contributes.
+   *
+   * @generated from field: apps.v1.UI ui = 11;
+   */
+  ui?: UI | undefined;
+
+  /**
+   * OPTIONAL. Inbound webhook declaration. If present, the gateway routes
+   * webhooks for this app to `${middleware.url}${inbound.webhook.path}`.
+   *
+   * @generated from field: apps.v1.Inbound inbound = 12;
+   */
+  inbound?: Inbound | undefined;
+
+  /**
+   * What the operator turns on and off as a whole, each with the storage it
+   * keeps. See Feature.
+   *
+   * @generated from field: repeated apps.v1.Feature features = 13;
+   */
+  features: Feature[];
+};
+
+/**
+ * Describes the message apps.v1.AppConfig.
+ * Use `create(AppConfigSchema)` to create a new message.
+ */
+export declare const AppConfigSchema: GenMessage<AppConfig>;
+
+/**
+ * A feature of the app: something the operator turns on or off as a whole at
+ * setup, such as a store's preorders or its back-in-stock alerts.
+ *
+ * A feature KEEPS its storage. The sources it names are the storage it writes,
+ * and they exist only while it is on: turning it on is what creates them, which
+ * the operator approves at setup, and while it is off they are declined, so no
+ * model is made and the operations that need them are not registered. Each of
+ * them is optional, since switching the feature off drops it, and belongs to
+ * no other feature.
+ *
+ * A feature may also name a setting, when the app itself has to know whether
+ * it is on: for example because it changes the access the app asks its vendor
+ * for. The setup writes that setting as the switch. A feature with none is on
+ * while its storage is.
+ *
+ * @generated from message apps.v1.Feature
+ */
+export declare type Feature = Message<"apps.v1.Feature"> & {
+  /**
+   * REQUIRED. Kebab-case, unique among the manifest's features.
+   *
+   * @generated from field: string key = 1;
+   */
+  key: string;
+
+  /**
+   * REQUIRED. What the setup calls it.
+   *
+   * @generated from field: string title = 2;
+   */
+  title: string;
+
+  /**
+   * What turning it on does, in a sentence or two.
+   *
+   * @generated from field: string description = 3;
+   */
+  description: string;
+
+  /**
+   * The boolean property of settings_schema that says whether it is on, when
+   * the app reads one. Empty when the feature is on exactly while its storage
+   * is.
+   *
+   * @generated from field: string setting = 4;
+   */
+  setting: string;
+
+  /**
+   * The sources this feature keeps.
+   *
+   * @generated from field: repeated string sources = 5;
+   */
+  sources: string[];
+};
+
+/**
+ * Describes the message apps.v1.Feature.
+ * Use `create(FeatureSchema)` to create a new message.
+ */
+export declare const FeatureSchema: GenMessage<Feature>;
+
+/**
+ * @generated from message apps.v1.Metadata
+ */
+export declare type Metadata = Message<"apps.v1.Metadata"> & {
+  /**
+   * e.g. "Shopify"
+   *
+   * @generated from field: string display_name = 1;
+   */
+  displayName: string;
+
+  /**
+   * @generated from field: string description = 2;
+   */
+  description: string;
+
+  /**
+   * icon key or URL
+   *
+   * @generated from field: string icon = 3;
+   */
+  icon: string;
+
+  /**
+   * @generated from field: string author = 4;
+   */
+  author: string;
+
+  /**
+   * public docs URL, optional
+   *
+   * @generated from field: string homepage = 5;
+   */
+  homepage: string;
+};
+
+/**
+ * Describes the message apps.v1.Metadata.
+ * Use `create(MetadataSchema)` to create a new message.
+ */
+export declare const MetadataSchema: GenMessage<Metadata>;
+
+/**
+ * @generated from message apps.v1.Middleware
+ */
+export declare type Middleware = Message<"apps.v1.Middleware"> & {
+  /**
+   * REQUIRED within Middleware. https URL of the app's service.
+   *
+   * @generated from field: string url = 1;
+   */
+  url: string;
+};
+
+/**
+ * Describes the message apps.v1.Middleware.
+ * Use `create(MiddlewareSchema)` to create a new message.
+ */
+export declare const MiddlewareSchema: GenMessage<Middleware>;
+
+/**
+ * @generated from message apps.v1.Credentials
+ */
+export declare type Credentials = Message<"apps.v1.Credentials"> & {
+  /**
+   * @generated from field: apps.v1.Credentials.Strategy strategy = 1;
+   */
+  strategy: Credentials_Strategy;
+
+  /**
+   * Shape of the admin form for strategies that take structured values.
+   * JSON Schema.
+   *
+   * @generated from field: optional google.protobuf.Struct schema = 2;
+   */
+  schema?: JsonObject | undefined;
+
+  /**
+   * Required only when strategy is OAUTH.
+   *
+   * @generated from field: optional apps.v1.OAuthConfig oauth = 3;
+   */
+  oauth?: OAuthConfig | undefined;
+};
+
+/**
+ * Describes the message apps.v1.Credentials.
+ * Use `create(CredentialsSchema)` to create a new message.
+ */
+export declare const CredentialsSchema: GenMessage<Credentials>;
+
+/**
+ * @generated from enum apps.v1.Credentials.Strategy
+ */
+export enum Credentials_Strategy {
+  /**
+   * @generated from enum value: STRATEGY_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * @generated from enum value: STRATEGY_OAUTH = 1;
+   */
+  OAUTH = 1,
+
+  /**
+   * @generated from enum value: STRATEGY_API_KEY = 2;
+   */
+  API_KEY = 2,
+
+  /**
+   * @generated from enum value: STRATEGY_SHARED_SECRET = 3;
+   */
+  SHARED_SECRET = 3,
+
+  /**
+   * @generated from enum value: STRATEGY_SSH_KEY = 4;
+   */
+  SSH_KEY = 4,
+
+  /**
+   * @generated from enum value: STRATEGY_NONE = 5;
+   */
+  NONE = 5,
+
+  /**
+   * @generated from enum value: STRATEGY_MANAGED = 6;
+   */
+  MANAGED = 6,
+}
+
+/**
+ * Describes the enum apps.v1.Credentials.Strategy.
+ */
+export declare const Credentials_StrategySchema: GenEnum<Credentials_Strategy>;
+
+/**
+ * @generated from message apps.v1.OAuthConfig
+ */
+export declare type OAuthConfig = Message<"apps.v1.OAuthConfig"> & {
+  /**
+   * e.g. "/authorize/start"
+   *
+   * @generated from field: string authorize_start_path = 1;
+   */
+  authorizeStartPath: string;
+
+  /**
+   * e.g. "/authorize/callback"
+   *
+   * @generated from field: string authorize_callback_path = 2;
+   */
+  authorizeCallbackPath: string;
+};
+
+/**
+ * Describes the message apps.v1.OAuthConfig.
+ * Use `create(OAuthConfigSchema)` to create a new message.
+ */
+export declare const OAuthConfigSchema: GenMessage<OAuthConfig>;
+
+/**
+ * @generated from message apps.v1.Inbound
+ */
+export declare type Inbound = Message<"apps.v1.Inbound"> & {
+  /**
+   * @generated from field: apps.v1.Webhook webhook = 1;
+   */
+  webhook?: Webhook | undefined;
+
+  /**
+   * Deliveries a vendor addresses to the APP rather than to one install.
+   *
+   * A vendor's privacy and compliance webhooks are usually configured once, in
+   * the vendor's own dashboard, for the whole app. They carry an account
+   * identifier and no project, so they cannot use the per-install webhook
+   * address: that address is one foir MINTED and can therefore verify, and
+   * this one is not.
+   *
+   * @generated from field: apps.v1.AccountWebhook account = 2;
+   */
+  account?: AccountWebhook | undefined;
+};
+
+/**
+ * Describes the message apps.v1.Inbound.
+ * Use `create(InboundSchema)` to create a new message.
+ */
+export declare const InboundSchema: GenMessage<Inbound>;
+
+/**
+ * @generated from message apps.v1.Webhook
+ */
+export declare type Webhook = Message<"apps.v1.Webhook"> & {
+  /**
+   * Path on middleware.url that receives webhook deliveries. The gateway
+   * proxies deliveries with an attached scoped token.
+   *
+   * @generated from field: string path = 1;
+   */
+  path: string;
+};
+
+/**
+ * Describes the message apps.v1.Webhook.
+ * Use `create(WebhookSchema)` to create a new message.
+ */
+export declare const WebhookSchema: GenMessage<Webhook>;
+
+/**
+ * How foir gets from the account a delivery names to the installs holding it.
+ *
+ * Several installs holding one account is NORMAL, not an anomaly, and all of
+ * them are delivered to. An install is scoped to a project, and a vendor that
+ * allows only one install per account is describing its own product rather
+ * than foir's: making that a foir constraint would also couple tenants, since
+ * a global uniqueness rule lets one tenant block another and lets the refusal
+ * tell them why.
+ *
+ * foir verifies NOTHING about the body on this lane and cannot: the vendor
+ * signs with a secret the app's own middleware holds, and there is no
+ * vocabulary here for which header carries it or how it is computed. The
+ * middleware verifies, and until it does the delivery has bought nothing.
+ *
+ * @generated from message apps.v1.AccountWebhook
+ */
+export declare type AccountWebhook = Message<"apps.v1.AccountWebhook"> & {
+  /**
+   * Path on middleware.url that receives these deliveries. Separate from
+   * Webhook.path because the two carry different guarantees and a handler that
+   * confuses them would treat an unverified app-wide delivery as a verified
+   * per-install one.
+   *
+   * @generated from field: string path = 1;
+   */
+  path: string;
+
+  /**
+   * Which setting holds the account identifier, as a key of the app's own
+   * settings. For a store integration that is the store's domain, supplied by
+   * the operator at install.
+   *
+   * ONE WORD. This key is read from stored manifest JSON by SQL, and protojson
+   * accepts both snake_case and camelCase on input, so a two-word name would
+   * be stored two ways by two authors and the query would find one of them.
+   *
+   * @generated from field: string setting = 2;
+   */
+  setting: string;
+
+  /**
+   * Where the account identifier is read from in the delivery, as a prefixed
+   * token. `h:x-shopify-shop-domain` reads a header. The prefix is what lets a
+   * later form be a new value here rather than a new address every app author
+   * has to re-paste.
+   *
+   * @generated from field: string source = 3;
+   */
+  source: string;
+};
+
+/**
+ * Describes the message apps.v1.AccountWebhook.
+ * Use `create(AccountWebhookSchema)` to create a new message.
+ */
+export declare const AccountWebhookSchema: GenMessage<AccountWebhook>;
+
+/**
+ * A source type the app can deliver inbound. At install, admin maps this
+ * type onto a project model key and maps each suggested field onto a model
+ * field key.
+ *
+ * @generated from message apps.v1.SourceType
+ */
+export declare type SourceType = Message<"apps.v1.SourceType"> & {
+  /**
+   * @generated from field: string label = 1;
+   */
+  label: string;
+
+  /**
+   * @generated from field: map<string, apps.v1.SuggestedField> fields = 2;
+   */
+  fields: { [key: string]: SuggestedField };
+
+  /**
+   * @generated from field: string natural_key = 3;
+   */
+  naturalKey: string;
+
+  /**
+   * When true, an install may leave this type unmapped: coverage no longer
+   * demands an entry for it, and the operations, hooks and placements whose
+   * $placeholders reference it are DROPPED rather than failing to resolve.
+   * Default false, so every existing manifest keeps today's behaviour.
+   *
+   * This is what makes "sync customers, or don't" expressible. Without it an
+   * app either forces the operator to map a model they do not want — and the
+   * operation carries records:write:<model> regardless — or cannot offer the
+   * source at all.
+   *
+   * @generated from field: bool optional = 4;
+   */
+  optional: boolean;
+
+  /**
+   * When true, the platform provisions the model and resolves $placeholders
+   * against it, but expects NO inbound sync: the app owns the write path and
+   * there is no external system on the other end.
+   *
+   * Still mapped — the operator chooses which model it targets, because
+   * capability resolution needs that answer. What it is not is SYNCED, which
+   * is the whole distinction from `optional` above; the two compose freely.
+   *
+   * AppInstallPreview must present it as storage the app needs rather than as
+   * something the external system will send. Presenting it as a sync mapping
+   * is not a cosmetic slip: it is a false statement in the one screen whose
+   * job is to tell the operator what the app will do.
+   *
+   * @generated from field: bool provision_only = 5;
+   */
+  provisionOnly: boolean;
+
+  /**
+   * When set, an install may READ THIS SOURCE LIVE from the host instead of
+   * syncing a copy of it: Foir keeps the record and the host's key for it, and
+   * the host keeps the data. See SourceReference. The install chooses per
+   * source (apps.v1.SourceMapping.mode); a new install reads live wherever the
+   * source offers it, and an install that chose to keep a copy syncs as before.
+   *
+   * @generated from field: apps.v1.SourceReference reference = 6;
+   */
+  reference?: SourceReference | undefined;
+
+  /**
+   * Who each row of this source's model belongs to. Unset says nothing, and
+   * the source maps onto a model owned at any level, as before.
+   *
+   * Set, it is a requirement the install holds the operator to: the source may
+   * only be mapped onto a model owned at this level, and the guided setup
+   * creates the model that way. It exists for storage whose meaning depends on
+   * who can read it. A wishlist the app writes for each customer is private to
+   * that customer only if its model is customer-owned; mapped onto a
+   * project-owned model, every row is readable by the project's public key.
+   *
+   * CUSTOMER requires provision_only or `identity`: a sync writes what the
+   * external system sends, and only `identity` gives each row a customer to
+   * own it.
+   *
+   * @generated from field: apps.v1.StorageOwner owner = 7;
+   */
+  owner: StorageOwner;
+
+  /**
+   * The app's word that this storage starts on in the guided setup. The
+   * operator can still decline it, and declining still drops what references
+   * it: this is a default, not a requirement.
+   *
+   * Only for a source that is both `optional` and `provision_only`, and a
+   * manifest that sets it anywhere else is refused. A required source is
+   * always mapped, so it would mean nothing. A synced source's default is
+   * discovery's call for the account in front of it
+   * (DiscoveredSource.recommended), so a flag here would be ignored. Storage has
+   * no account behind it to discover, which leaves the app's own word as the
+   * only one there is.
+   *
+   * @generated from field: bool recommended = 8;
+   */
+  recommended: boolean;
+
+  /**
+   * The fields that find one of this source's records whatever its natural key
+   * is now: the external system's own id for the object, where the natural key
+   * is a value the system lets its users change, such as a product's handle.
+   * One to four of this source's `fields`, each a required scalar.
+   *
+   * It is what lets the app follow a key the external system changed. Written
+   * under its new key, the object is refused because another record already
+   * holds its id, and the app renames that record to the new key and writes
+   * again, rather than creating a second record and leaving the first behind.
+   * That refusal needs the model to declare a lookup over the model fields
+   * these fields map to, so the install is held to it: a mapping onto a model
+   * without that lookup is refused, naming it, and the guided setup creates the
+   * model with it. A mapping keyed on these same fields needs no lookup, since
+   * its key never changes.
+   *
+   * @generated from field: repeated string lookup = 9;
+   */
+  lookup: string[];
+
+  /**
+   * The field that names the customer each row belongs to, as the external
+   * system identifies them: a customer's id there, which is also the subject
+   * of their sign-in with it. One of this source's `fields`, a required scalar,
+   * and only on a customer-owned source (`owner` CUSTOMER).
+   *
+   * It is what lets a sync write customer-owned rows. The platform resolves the
+   * value to a Foir customer through the customer sign-in the install pairs
+   * with the source (SourceMapping.identity_provider), at the install's level:
+   * the customer who signs in with that identity, or one made for it. Each
+   * customer holds one row of the source, their profile, so the source has no
+   * natural key; the customer is the key. Never matched by email.
+   *
+   * @generated from field: string identity = 10;
+   */
+  identity: string;
+};
+
+/**
+ * Describes the message apps.v1.SourceType.
+ * Use `create(SourceTypeSchema)` to create a new message.
+ */
+export declare const SourceTypeSchema: GenMessage<SourceType>;
+
+/**
+ * SourceReference is how a source is read live. At install the platform
+ * provisions a FIELD operation on the mapped model, named <app><Source> in the
+ * schema (`product { shopifyProduct { ... } }`), whose resolver calls the host
+ * through the request below with the record's key, and answers with `fields`.
+ *
+ * The request reads the install's own credential through
+ * {{credential.<field>}}, resolved from the vault at the install's level when
+ * the call is made: a field the manifest's credential declares, and nothing
+ * else. The host may be filled from it (a store's own domain), but only within
+ * `hosts`: the filled host must match one of them and be a public address, or
+ * the call is refused before anything is sent. Every other value is escaped
+ * for where it stands, as an operation's request template is.
+ *
+ * A live field is not filterable or sortable: nothing about it is stored. An
+ * operator who needs to filter on host fields inside Foir keeps a copy.
+ *
+ * @generated from message apps.v1.SourceReference
+ */
+export declare type SourceReference = Message<"apps.v1.SourceReference"> & {
+  /**
+   * The source field holding the host's id for an object. It is one of the
+   * source's `fields`; the model field it is mapped to is the resolver's parent
+   * field, read as {{parent.<key_field>}}.
+   *
+   * @generated from field: string key_field = 1;
+   */
+  keyField: string;
+
+  /**
+   * What the live read answers, by name: the resolver's output shape.
+   *
+   * @generated from field: map<string, apps.v1.SuggestedField> fields = 2;
+   */
+  fields: { [key: string]: SuggestedField };
+
+  /**
+   * The absolute https URL the read calls. The host may be
+   * {{credential.<field>}}, or contain one as a leading label.
+   *
+   * @generated from field: string endpoint = 3;
+   */
+  endpoint: string;
+
+  /**
+   * The hosts the endpoint may resolve to: exact names, or "*.<domain>" for any
+   * single label under it. At least one.
+   *
+   * @generated from field: repeated string hosts = 4;
+   */
+  hosts: string[];
+
+  /**
+   * @generated from field: apps.v1.ReferenceRequest request = 5;
+   */
+  request?: ReferenceRequest | undefined;
+
+  /**
+   * A jq program over the host's answer, producing `fields`. With
+   * request.batch_capable it maps the batch's answer back by index.
+   *
+   * @generated from field: string response_transform = 6;
+   */
+  responseTransform: string;
+
+  /**
+   * How long one live answer is shared across callers, in seconds. 0 is the
+   * platform default (60). Catalogue data is the same for everyone, so the
+   * cache is shared, and it is what keeps a host's rate limit affordable.
+   *
+   * @generated from field: int32 cache_max_age_seconds = 7;
+   */
+  cacheMaxAgeSeconds: number;
+};
+
+/**
+ * Describes the message apps.v1.SourceReference.
+ * Use `create(SourceReferenceSchema)` to create a new message.
+ */
+export declare const SourceReferenceSchema: GenMessage<SourceReference>;
+
+/**
+ * ReferenceRequest shapes the live read, as operations.v1.RequestTemplate
+ * shapes an operation's call: {{parent.X}}, {{credential.X}} and {{context.X}}
+ * are filled in at call time.
+ *
+ * @generated from message apps.v1.ReferenceRequest
+ */
+export declare type ReferenceRequest = Message<"apps.v1.ReferenceRequest"> & {
+  /**
+   * GET / POST; defaults to POST
+   *
+   * @generated from field: string method = 1;
+   */
+  method: string;
+
+  /**
+   * @generated from field: string path_template = 2;
+   */
+  pathTemplate: string;
+
+  /**
+   * @generated from field: map<string, string> query = 3;
+   */
+  query: { [key: string]: string };
+
+  /**
+   * @generated from field: map<string, string> headers = 4;
+   */
+  headers: { [key: string]: string };
+
+  /**
+   * @generated from field: string body_template = 5;
+   */
+  bodyTemplate: string;
+
+  /**
+   * One host request for the page's whole deduplicated set of records, as
+   * {{items}}, instead of one per record.
+   *
+   * @generated from field: bool batch_capable = 6;
+   */
+  batchCapable: boolean;
+};
+
+/**
+ * Describes the message apps.v1.ReferenceRequest.
+ * Use `create(ReferenceRequestSchema)` to create a new message.
+ */
+export declare const ReferenceRequestSchema: GenMessage<ReferenceRequest>;
+
+/**
+ * A sink contract the app needs outbound. At install, admin maps this
+ * contract onto a project model and maps each field onto a model field.
+ *
+ * @generated from message apps.v1.SinkContract
+ */
+export declare type SinkContract = Message<"apps.v1.SinkContract"> & {
+  /**
+   * @generated from field: string label = 1;
+   */
+  label: string;
+
+  /**
+   * Fields the app needs. Individual entries can be required: false.
+   *
+   * @generated from field: map<string, apps.v1.SinkField> fields = 2;
+   */
+  fields: { [key: string]: SinkField };
+
+  /**
+   * Which mapped field is the natural key for the external system's upsert.
+   *
+   * @generated from field: string natural_key = 3;
+   */
+  naturalKey: string;
+
+  /**
+   * As SourceType.optional: an install may leave this contract unmapped, and
+   * what references it is dropped instead of failing to resolve.
+   *
+   * @generated from field: bool optional = 4;
+   */
+  optional: boolean;
+};
+
+/**
+ * Describes the message apps.v1.SinkContract.
+ * Use `create(SinkContractSchema)` to create a new message.
+ */
+export declare const SinkContractSchema: GenMessage<SinkContract>;
+
+/**
+ * @generated from message apps.v1.SuggestedField
+ */
+export declare type SuggestedField = Message<"apps.v1.SuggestedField"> & {
+  /**
+   * resolves to platform FieldType enum
+   *
+   * @generated from field: string type = 1;
+   */
+  type: string;
+
+  /**
+   * @generated from field: optional string label = 2;
+   */
+  label?: string | undefined;
+
+  /**
+   * @generated from field: optional bool required = 3;
+   */
+  required?: boolean | undefined;
+
+  /**
+   * @generated from field: optional google.protobuf.Struct config = 4;
+   */
+  config?: JsonObject | undefined;
+
+  /**
+   * What THE EXTERNAL SYSTEM can support for this field. Absent means
+   * SOURCE_ONLY.
+   *
+   * READ IT AS A SET OF LEGS, NOT AS A RANK: SOURCE_ONLY is {inbound},
+   * SINK_ONLY is {outbound}, BIDIRECTIONAL is both. The operator's choice must
+   * be a SUBSET of what is declared here, so a SINK_ONLY declaration permits
+   * only SINK_ONLY — it does not permit SOURCE_ONLY as some lesser option.
+   *
+   * The enum numbers are not an ordering. `chosen <= supported` compiles, reads
+   * plausibly, and is wrong: it accepts SOURCE_ONLY(1) against a declared
+   * SINK_ONLY(2), which is the one comparison a rank would let through and a
+   * subset check refuses.
+   *
+   * Declared by the app author because they are the only party who knows.
+   * Stripe's Price.unit_amount is the canonical case: it is immutable, so
+   * writing an edit back is not a slow path, it is a thing that cannot happen.
+   * An operator choosing BIDIRECTIONAL for such a field has to be refused at
+   * configuration time rather than discovering it when the first edit fails
+   * somewhere they are not looking.
+   *
+   * @generated from field: optional apps.v1.FieldSyncDirection supported_direction = 5;
+   */
+  supportedDirection?: FieldSyncDirection | undefined;
+
+  /**
+   * The app counts, groups or sorts its records by this field, so the model
+   * field it maps to should be indexed (a model field's `queryable`). The
+   * guided setup creates the field that way. Declared by the app author, who
+   * knows which of their fields their own reads depend on: an app keeping a
+   * shopper's back-in-stock requests counts them by variant, and an index is
+   * what lets it ask the platform for the count rather than read every row.
+   *
+   * It says what the app needs of a model the setup creates, and nothing
+   * stricter: filtering needs no index, and an operator mapping onto a model
+   * of their own may index it or not. An app asking to count by a field that
+   * is not indexed is refused by the aggregate, naming the field.
+   *
+   * @generated from field: optional bool queryable = 6;
+   */
+  queryable?: boolean | undefined;
+};
+
+/**
+ * Describes the message apps.v1.SuggestedField.
+ * Use `create(SuggestedFieldSchema)` to create a new message.
+ */
+export declare const SuggestedFieldSchema: GenMessage<SuggestedField>;
+
+/**
+ * A field in a SinkContract. Renamed from the older RequiredField — individual
+ * entries can still be required: false; the message name now reflects the
+ * surrounding contract, not the required flag.
+ *
+ * @generated from message apps.v1.SinkField
+ */
+export declare type SinkField = Message<"apps.v1.SinkField"> & {
+  /**
+   * Type hint only. Sink fields never carry field-type-specific configuration
+   * (select options, defaults, validation ranges). That belongs on the
+   * mapped project model field.
+   *
+   * @generated from field: string type = 1;
+   */
+  type: string;
+
+  /**
+   * e.g. "source-url", "target-url", "status-code"
+   *
+   * @generated from field: string semantic = 2;
+   */
+  semantic: string;
+
+  /**
+   * @generated from field: bool required = 3;
+   */
+  required: boolean;
+
+  /**
+   * @generated from field: optional string label = 4;
+   */
+  label?: string | undefined;
+};
+
+/**
+ * Describes the message apps.v1.SinkField.
+ * Use `create(SinkFieldSchema)` to create a new message.
+ */
+export declare const SinkFieldSchema: GenMessage<SinkField>;
+
+/**
+ * @generated from message apps.v1.Operation
+ */
+export declare type Operation = Message<"apps.v1.Operation"> & {
+  /**
+   * REQUIRED. Kebab-case, unique within the manifest. Keys starting with
+   * `__` are platform-reserved (currently __uninstall, __validate_credentials).
+   * On install the platform prefixes the stored key as `<appName>/<key>`
+   * for namespace isolation across apps.
+   *
+   * @generated from field: string key = 1;
+   */
+  key: string;
+
+  /**
+   * @generated from field: string name = 2;
+   */
+  name: string;
+
+  /**
+   * @generated from field: optional string description = 3;
+   */
+  description?: string | undefined;
+
+  /**
+   * REQUIRED. Path on middleware.url that handles invocation.
+   *
+   * @generated from field: string endpoint = 4;
+   */
+  endpoint: string;
+
+  /**
+   * REQUIRED. Capability set the platform mints the scoped token with.
+   * Each string is one of ManifestCapability, as its option spells it; a
+   * per-model capability with no model (bare records:read) is rejected.
+   * Placeholders `$<sourceType>` / `$<sinkContract>` inside model-scoped
+   * capabilities are resolved to concrete model keys at ConfirmInstallApp.
+   *
+   * @generated from field: repeated string capabilities = 5;
+   */
+  capabilities: string[];
+
+  /**
+   * @generated from field: optional int32 timeout_ms = 6;
+   */
+  timeoutMs?: number | undefined;
+
+  /**
+   * @generated from field: optional google.protobuf.Struct retry_policy = 7;
+   */
+  retryPolicy?: JsonObject | undefined;
+
+  /**
+   * @generated from field: optional google.protobuf.Struct input_schema = 8;
+   */
+  inputSchema?: JsonObject | undefined;
+
+  /**
+   * @generated from field: optional google.protobuf.Struct output_schema = 9;
+   */
+  outputSchema?: JsonObject | undefined;
+
+  /**
+   * @generated from field: optional bool supports_async = 10;
+   */
+  supportsAsync?: boolean | undefined;
+
+  /**
+   * When true, platform auto-enqueues this operation after a successful
+   * ConfirmInstallApp (and, for apps declaring __validate_credentials, after
+   * that gate passes). Multiple operations with run_after_install=true are
+   * dispatched in manifest declaration order. A failure here emits the
+   * app_event `post_install_op_failed` but does NOT roll back the install;
+   * the admin retries via the standard op-dispatch UI.
+   *
+   * @generated from field: bool run_after_install = 11;
+   */
+  runAfterInstall: boolean;
+
+  /**
+   * When true, the operation works on whichever of its sources and sinks the
+   * install maps. A capability naming one left unmapped (an optional source
+   * the operator declined, or a source of a held install still being set up)
+   * is left out of the resolved set, and the operation is kept.
+   *
+   * When false, the default, such an operation is dropped instead: it is not
+   * created, and nothing dispatches it. That is the safe answer for an
+   * operation that would fail holding fewer capabilities than it declared.
+   *
+   * An operation that sets this cannot find its models by their position in
+   * its capability list, because an entry may be missing. It finds each one by
+   * its source or sink name in the install's mappings.
+   *
+   * @generated from field: bool runs_on_mapped_sources = 12;
+   */
+  runsOnMappedSources: boolean;
+};
+
+/**
+ * Describes the message apps.v1.Operation.
+ * Use `create(OperationSchema)` to create a new message.
+ */
+export declare const OperationSchema: GenMessage<Operation>;
+
+/**
+ * ManifestCapabilitySpec is how one ManifestCapability is written in a manifest.
+ *
+ * @generated from message apps.v1.ManifestCapabilitySpec
+ */
+export declare type ManifestCapabilitySpec = Message<"apps.v1.ManifestCapabilitySpec"> & {
+  /**
+   * The capability as declared. When per_model is set it is the prefix a model
+   * follows, colon included: `records:read:` is declared as
+   * `records:read:<model>`, or with a `$<source>` or `$<sink>` placeholder the
+   * install resolves to the model mapped there.
+   *
+   * @generated from field: string declares = 1;
+   */
+  declares: string;
+
+  /**
+   * Declared once per model. Without its model the capability is refused.
+   *
+   * @generated from field: bool per_model = 2;
+   */
+  perModel: boolean;
+};
+
+/**
+ * Describes the message apps.v1.ManifestCapabilitySpec.
+ * Use `create(ManifestCapabilitySpecSchema)` to create a new message.
+ */
+export declare const ManifestCapabilitySpecSchema: GenMessage<ManifestCapabilitySpec>;
+
+/**
+ * @generated from message apps.v1.Hook
+ */
+export declare type Hook = Message<"apps.v1.Hook"> & {
+  /**
+   * @generated from field: string key = 1;
+   */
+  key: string;
+
+  /**
+   * @generated from field: string name = 2;
+   */
+  name: string;
+
+  /**
+   * REQUIRED. Record-event identifier: RECORD_CREATED, RECORD_UPDATED,
+   * RECORD_DELETED, RECORD_PUBLISHED, ...
+   *
+   * @generated from field: string event = 3;
+   */
+  event: string;
+
+  /**
+   * REQUIRED. Filter. `{ sourceType: "product" }`, `{ sinkContract: "redirect" }`,
+   * or `{ modelKey: "..." }`. Resolved to concrete modelKey at install.
+   *
+   * @generated from field: google.protobuf.Struct filter = 4;
+   */
+  filter?: JsonObject | undefined;
+
+  /**
+   * REQUIRED. Operation key from the same manifest's operations list.
+   * Resolved to the namespaced form (<appName>/<key>) at install.
+   *
+   * @generated from field: string operation = 5;
+   */
+  operation: string;
+};
+
+/**
+ * Describes the message apps.v1.Hook.
+ * Use `create(HookSchema)` to create a new message.
+ */
+export declare const HookSchema: GenMessage<Hook>;
+
+/**
+ * @generated from message apps.v1.UI
+ */
+export declare type UI = Message<"apps.v1.UI"> & {
+  /**
+   * @generated from field: repeated apps.v1.PlacementDeclaration placements = 1;
+   */
+  placements: PlacementDeclaration[];
+};
+
+/**
+ * Describes the message apps.v1.UI.
+ * Use `create(UISchema)` to create a new message.
+ */
+export declare const UISchema: GenMessage<UI>;
+
+/**
+ * The manifest-time declaration of a placement. At install, ConfirmInstallApp
+ * translates each declaration into a placements.v1.CreatePlacementRequest
+ * against the first-class PlacementsService. The persisted row has
+ * additional platform-assigned fields (id, tenant_id, project_id, config_id,
+ * timestamps) that aren't in the manifest.
+ *
+ * @generated from message apps.v1.PlacementDeclaration
+ */
+export declare type PlacementDeclaration = Message<"apps.v1.PlacementDeclaration"> & {
+  /**
+   * REQUIRED. Kebab-case. Unique within this manifest's ui.placements.
+   * Stable identifier used by admin UI for keying mapping choices
+   * (field_selected_at_install), by update-diff matching, and by the
+   * persisted placements row's UNIQUE (config_id, key).
+   *
+   * @generated from field: string key = 1;
+   */
+  key: string;
+
+  /**
+   * @generated from field: apps.v1.PlacementDeclaration.Target target = 2;
+   */
+  target: PlacementDeclaration_Target;
+
+  /**
+   * REQUIRED for MAIN_EDITOR, SIDEBAR, FIELD. Model key. Use "*" for
+   * placements that apply to every record. May reference a sourceType /
+   * sinkContract name from this manifest (resolved at install) OR a
+   * literal model key ("*" or a known project model).
+   *
+   * @generated from field: optional string model = 3;
+   */
+  model?: string | undefined;
+
+  /**
+   * REQUIRED for FIELD when field_selected_at_install is false. Must be
+   * empty when field_selected_at_install is true.
+   *
+   * @generated from field: optional string field = 4;
+   */
+  field?: string | undefined;
+
+  /**
+   * FIELD-only. When true, the admin chooses the specific field during
+   * the mapping step (keyed by placement.key).
+   *
+   * @generated from field: bool field_selected_at_install = 5;
+   */
+  fieldSelectedAtInstall: boolean;
+
+  /**
+   * REQUIRED for MAIN_EDITOR, SIDEBAR. Tab slug.
+   *
+   * @generated from field: optional string tab = 6;
+   */
+  tab?: string | undefined;
+
+  /**
+   * REQUIRED for all. Human-readable title.
+   *
+   * @generated from field: string title = 7;
+   */
+  title: string;
+
+  /**
+   * REQUIRED. https URL the iframe loads.
+   *
+   * @generated from field: string url = 8;
+   */
+  url: string;
+
+  /**
+   * MAIN_EDITOR only. If true, replaces the default record editor.
+   *
+   * @generated from field: optional bool replaces_default = 9;
+   */
+  replacesDefault?: boolean | undefined;
+
+  /**
+   * Free-form hints (icon, ordering, badge text).
+   *
+   * @generated from field: optional google.protobuf.Struct hints = 10;
+   */
+  hints?: JsonObject | undefined;
+
+  /**
+   * What a TARGET_FULL_PAGE page asks to act with: API scopes such as
+   * "records:read:order". The console hands the page a short-lived token that
+   * acts as the operator looking at it, at the install's level, carrying the
+   * overlap of these scopes with what that operator holds there and never more.
+   * An operator standing beneath the install is given the reads only. The
+   * install preview lists them, so installing the app is agreeing to them.
+   * Refused on every other target: a record-bound placement is handed its
+   * record, not a credential.
+   *
+   * @generated from field: repeated string scopes = 11;
+   */
+  scopes: string[];
+
+  /**
+   * The settings_schema properties this TARGET_FULL_PAGE page may read and
+   * change: how a turned-on feature behaves, such as when a back-in-stock
+   * alert goes out or a preorder's deposit. The setup owns what the app is
+   * given, so a feature's switch (Feature.setting), the setting that names the
+   * external account, credentials and mappings are never among them. Changing
+   * or reading one needs apps:write, which the placement declares in scopes
+   * and the operator holds at the install's level, as in the setup.
+   *
+   * @generated from field: repeated string settings = 12;
+   */
+  settings: string[];
+};
+
+/**
+ * Describes the message apps.v1.PlacementDeclaration.
+ * Use `create(PlacementDeclarationSchema)` to create a new message.
+ */
+export declare const PlacementDeclarationSchema: GenMessage<PlacementDeclaration>;
+
+/**
+ * @generated from enum apps.v1.PlacementDeclaration.Target
+ */
+export enum PlacementDeclaration_Target {
+  /**
+   * @generated from enum value: TARGET_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * top-level admin page
+   *
+   * @generated from enum value: TARGET_FULL_PAGE = 1;
+   */
+  FULL_PAGE = 1,
+
+  /**
+   * record's primary editor
+   *
+   * @generated from enum value: TARGET_MAIN_EDITOR = 2;
+   */
+  MAIN_EDITOR = 2,
+
+  /**
+   * panel attached to a record editor
+   *
+   * @generated from enum value: TARGET_SIDEBAR = 3;
+   */
+  SIDEBAR = 3,
+
+  /**
+   * inline iframe for a specific field
+   *
+   * @generated from enum value: TARGET_FIELD = 4;
+   */
+  FIELD = 4,
+}
+
+/**
+ * Describes the enum apps.v1.PlacementDeclaration.Target.
+ */
+export declare const PlacementDeclaration_TargetSchema: GenEnum<PlacementDeclaration_Target>;
+
+/**
+ * Which way a mapped field's values travel between foir and an app's external
+ * system.
+ *
+ * READ THE NAMES FROM THE MANIFEST'S POINT OF VIEW, where a SourceType is
+ * something the external system SOURCES to foir. SOURCE_ONLY therefore means
+ * external -> foir; SINK_ONLY means foir -> external. The obvious misreading —
+ * that SOURCE_ONLY means foir is the source — is exactly backwards, so the
+ * names are spelled out on each value below rather than left to inference.
+ *
+ * @generated from enum apps.v1.FieldSyncDirection
+ */
+export enum FieldSyncDirection {
+  /**
+   * @generated from enum value: FIELD_SYNC_DIRECTION_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * External -> foir. The external system owns the value. The provisioned
+   * model field should carry access.write = ["scoped"], so an editor is
+   * REFUSED rather than having the edit silently overwritten by the next sync.
+   *
+   * @generated from enum value: FIELD_SYNC_DIRECTION_SOURCE_ONLY = 1;
+   */
+  SOURCE_ONLY = 1,
+
+  /**
+   * foir -> external. foir owns the value and pushes changes outward.
+   *
+   * @generated from enum value: FIELD_SYNC_DIRECTION_SINK_ONLY = 2;
+   */
+  SINK_ONLY = 2,
+
+  /**
+   * Both ways. Requires the manifest to have declared the field as supporting
+   * it, and requires the middleware to compare before writing on BOTH legs:
+   * the causation chain breaks loops inside foir but does not survive a round
+   * trip through a third party, so nothing else stops the echo.
+   *
+   * @generated from enum value: FIELD_SYNC_DIRECTION_BIDIRECTIONAL = 3;
+   */
+  BIDIRECTIONAL = 3,
+}
+
+/**
+ * Describes the enum apps.v1.FieldSyncDirection.
+ */
+export declare const FieldSyncDirectionSchema: GenEnum<FieldSyncDirection>;
+
+/**
+ * The level that owns each row of an app's storage: the three levels a model
+ * can be owned at, less the operator-private one, which no app writes.
+ *
+ * @generated from enum apps.v1.StorageOwner
+ */
+export enum StorageOwner {
+  /**
+   * @generated from enum value: STORAGE_OWNER_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * Project content: one set of rows for the whole project.
+   *
+   * @generated from enum value: STORAGE_OWNER_PROJECT = 1;
+   */
+  PROJECT = 1,
+
+  /**
+   * Each row belongs to an organisation of the project.
+   *
+   * @generated from enum value: STORAGE_OWNER_ORGANIZATION = 2;
+   */
+  ORGANIZATION = 2,
+
+  /**
+   * Each row belongs to a customer, and only they and the project read it.
+   *
+   * @generated from enum value: STORAGE_OWNER_CUSTOMER = 3;
+   */
+  CUSTOMER = 3,
+}
+
+/**
+ * Describes the enum apps.v1.StorageOwner.
+ */
+export declare const StorageOwnerSchema: GenEnum<StorageOwner>;
+
+/**
+ * @generated from enum apps.v1.ManifestCapability
+ */
+export enum ManifestCapability {
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * The install's own surface: its settings and mappings, its credential, and
+   * the status it reports.
+   *
+   * @generated from enum value: MANIFEST_CAPABILITY_CONFIG_READ = 1;
+   */
+  CONFIG_READ = 1,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_SECRETS_READ_APP = 2;
+   */
+  SECRETS_READ_APP = 2,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_SECRETS_PUT_APP = 3;
+   */
+  SECRETS_PUT_APP = 3,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_SECRETS_LIST_APP = 4;
+   */
+  SECRETS_LIST_APP = 4,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_SECRETS_DELETE_APP = 5;
+   */
+  SECRETS_DELETE_APP = 5,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_STATUS_WRITE = 6;
+   */
+  STATUS_WRITE = 6,
+
+  /**
+   * Files.
+   *
+   * @generated from enum value: MANIFEST_CAPABILITY_FILES_READ = 7;
+   */
+  FILES_READ = 7,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_FILES_LIST = 8;
+   */
+  FILES_LIST = 8,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_FILES_WRITE = 9;
+   */
+  FILES_WRITE = 9,
+
+  /**
+   * Customers: making the customers an operation attributes records to,
+   * telling them something, and setting a named customer's consent.
+   *
+   * @generated from enum value: MANIFEST_CAPABILITY_CUSTOMERS_WRITE = 10;
+   */
+  CUSTOMERS_WRITE = 10,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_NOTIFICATIONS_WRITE = 11;
+   */
+  NOTIFICATIONS_WRITE = 11,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_NOTIFICATIONS_CONSENT = 12;
+   */
+  NOTIFICATIONS_CONSENT = 12,
+
+  /**
+   * Reporting an ASYNC run's outcome.
+   *
+   * @generated from enum value: MANIFEST_CAPABILITY_OPERATIONS_COMPLETE = 13;
+   */
+  OPERATIONS_COMPLETE = 13,
+
+  /**
+   * Records, per model. Delete and publish are their own capabilities: write
+   * implies neither. Attribute is naming the customer a record belongs to.
+   *
+   * @generated from enum value: MANIFEST_CAPABILITY_RECORDS_READ = 20;
+   */
+  RECORDS_READ = 20,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_RECORDS_WRITE = 21;
+   */
+  RECORDS_WRITE = 21,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_RECORDS_DELETE = 22;
+   */
+  RECORDS_DELETE = 22,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_RECORDS_PUBLISH = 23;
+   */
+  RECORDS_PUBLISH = 23,
+
+  /**
+   * @generated from enum value: MANIFEST_CAPABILITY_RECORDS_ATTRIBUTE = 24;
+   */
+  RECORDS_ATTRIBUTE = 24,
+}
+
+/**
+ * Describes the enum apps.v1.ManifestCapability.
+ */
+export declare const ManifestCapabilitySchema: GenEnum<ManifestCapability>;
+
+/**
+ * 60003 is in the organisation-internal extension range, beside the intent
+ * option's 60001 and the config destination's 60002.
+ *
+ * @generated from extension: apps.v1.ManifestCapabilitySpec manifest_capability = 60003;
+ */
+export declare const manifest_capability: GenExtension<EnumValueOptions, ManifestCapabilitySpec>;
+