@wix/auto_sdk_gbp_media-uploads 1.0.0

package/build/es/index.typings.d.mts

@@ -0,0 +1,448 @@
+import { NonNullablePaths } from '@wix/sdk-types';
+
+/**
+ * One queued photo change on a Google Business Profile location: either an
+ * addition or a removal.
+ *
+ * Photo changes are queued and applied gradually rather than immediately,
+ * because Google accepts only about 10 edits per minute per Business Profile.
+ *
+ * Anything you can read here is either still waiting to be applied or has
+ * failed. A change that succeeded leaves nothing behind, so an empty list means
+ * the queue finished and everything worked. See `state`.
+ */
+interface MediaUpload {
+    /**
+     * Queued change ID.
+     * @format GUID
+     * @readonly
+     */
+    _id?: string;
+    /**
+     * ID of the location this change applies to. This is Google's location
+     * identifier.
+     * @immutable
+     * @minLength 1
+     * @maxLength 255
+     */
+    locationId?: string;
+    /**
+     * Groups the changes queued by one Bulk Create Media Uploads call. Useful for
+     * troubleshooting, since one save can produce more than one batch.
+     * @format GUID
+     * @readonly
+     */
+    batchId?: string;
+    /**
+     * Your own key for this photo: `logo`, `cover`, or `photo:<id>`.
+     *
+     * Set it to something stable and meaningful to you. It's how a failure is
+     * matched back to the photo that caused it, and it's part of what makes a
+     * repeated submission a duplicate rather than a second change.
+     * @maxLength 255
+     */
+    slotKey?: string;
+    /**
+     * Publicly reachable URL Google fetches the image from. Additions only.
+     *
+     * Keep it reachable well beyond the upload itself. A failure report renders
+     * this URL as a thumbnail, possibly weeks later.
+     * @maxLength 2048
+     */
+    sourceUrl?: string;
+    /** Where the photo appears on the profile. Additions only. */
+    category?: MediaCategoryWithLiterals;
+    /** Media type of the photo. Additions only. */
+    format?: MediaFormatWithLiterals;
+    /** Whether this change adds a photo to the profile or removes one. */
+    operation?: MediaUploadOperationWithLiterals;
+    /**
+     * Position in the order the queue applies changes, assigned by the server.
+     *
+     * Every removal comes before every addition, because Google rejects new photos
+     * on a profile that's already at its limit, so the old ones have to go first.
+     * Additions then follow as logo, cover, and gallery in the order given.
+     * @readonly
+     */
+    sequence?: number;
+    /**
+     * Whether this change is waiting, being applied, or has failed.
+     * @readonly
+     */
+    state?: MediaUploadStateWithLiterals;
+    /**
+     * How many times this change has been attempted.
+     * @readonly
+     */
+    attempts?: number;
+    /**
+     * Google's identifier for the photo to remove. Removals only.
+     * @maxLength 255
+     */
+    mediaKey?: string;
+    /**
+     * Why this change failed. Present only when `state` is `FAILED`.
+     * @readonly
+     */
+    failure?: MediaUploadFailure;
+    /**
+     * Date and time the change was queued.
+     * @readonly
+     */
+    _createdDate?: Date | null;
+    /**
+     * Date and time the change was last updated.
+     * @readonly
+     */
+    _updatedDate?: Date | null;
+    /**
+     * Revision number, incremented on every update.
+     * @readonly
+     */
+    revision?: string;
+}
+/**
+ * Where a media item is shown on the listing. Mirrors Google's mybusiness v4
+ * LocationAssociation.Category.
+ */
+declare enum MediaCategory {
+    COVER = "COVER",
+    PROFILE = "PROFILE",
+    LOGO = "LOGO",
+    EXTERIOR = "EXTERIOR",
+    INTERIOR = "INTERIOR",
+    PRODUCT = "PRODUCT",
+    AT_WORK = "AT_WORK",
+    FOOD_AND_DRINK = "FOOD_AND_DRINK",
+    MENU = "MENU",
+    COMMON_AREA = "COMMON_AREA",
+    ROOMS = "ROOMS",
+    TEAMS = "TEAMS",
+    ADDITIONAL = "ADDITIONAL"
+}
+/** @enumType */
+type MediaCategoryWithLiterals = MediaCategory | 'COVER' | 'PROFILE' | 'LOGO' | 'EXTERIOR' | 'INTERIOR' | 'PRODUCT' | 'AT_WORK' | 'FOOD_AND_DRINK' | 'MENU' | 'COMMON_AREA' | 'ROOMS' | 'TEAMS' | 'ADDITIONAL';
+/** Format of a media item. Mirrors Google's mybusiness v4 MediaFormat. */
+declare enum MediaFormat {
+    PHOTO = "PHOTO",
+    VIDEO = "VIDEO"
+}
+/** @enumType */
+type MediaFormatWithLiterals = MediaFormat | 'PHOTO' | 'VIDEO';
+/**
+ * Whether a queued change adds a photo to the profile or removes one.
+ *
+ * Removals are edits too and draw on the same per-minute budget as additions,
+ * which is why both go through the same queue.
+ */
+declare enum MediaUploadOperation {
+    /** Add a photo to the profile. */
+    CREATE = "CREATE",
+    /** Remove a photo from the profile. */
+    DELETE = "DELETE"
+}
+/** @enumType */
+type MediaUploadOperationWithLiterals = MediaUploadOperation | 'CREATE' | 'DELETE';
+/**
+ * Where a queued photo change is in its lifecycle.
+ *
+ * There's no state for success. A change that succeeds is removed from the
+ * queue, because Google's own media list is the record of what's live. So an
+ * empty queue means everything worked, and failures stay until the next
+ * submission for that location replaces them or you dismiss them.
+ *
+ * One consequence is worth knowing: because success leaves nothing behind, an
+ * addition that succeeded and one that never ran look the same afterwards. When
+ * the queue can't confirm an addition reached Google, it fails the change as
+ * `UPLOAD_UNVERIFIED` instead of retrying it, so you don't end up with the same
+ * photo twice. Removals carry no such risk and are retried freely.
+ */
+declare enum MediaUploadState {
+    /** Waiting its turn in the queue. */
+    PENDING = "PENDING",
+    /**
+     * Being applied to Google now. A change that stays here isn't one that never
+     * ran: its outcome isn't known yet.
+     */
+    UPLOADING = "UPLOADING",
+    /** Failed, and won't be retried. Kept until replaced or dismissed. */
+    FAILED = "FAILED"
+}
+/** @enumType */
+type MediaUploadStateWithLiterals = MediaUploadState | 'PENDING' | 'UPLOADING' | 'FAILED';
+/** Why a queued photo change failed. */
+interface MediaUploadFailure {
+    /** Why the change failed, in terms you can show a site owner. */
+    reason?: MediaUploadFailureReasonWithLiterals;
+}
+/**
+ * Why a photo change failed, in terms you can show a site owner.
+ *
+ * This is often the only account of the upload they'll ever see, and they may
+ * read it long after the fact, so it's worth surfacing rather than logging.
+ */
+declare enum MediaUploadFailureReason {
+    /** Below Google's minimum dimensions. */
+    IMAGE_TOO_SMALL = "IMAGE_TOO_SMALL",
+    /** Cover/logo ratio outside Google's accepted range. */
+    ASPECT_RATIO_REJECTED = "ASPECT_RATIO_REJECTED",
+    /** File type Google will not accept. */
+    FORMAT_UNSUPPORTED = "FORMAT_UNSUPPORTED",
+    /** Google could not fetch the image URL. */
+    SOURCE_UNREACHABLE = "SOURCE_UNREACHABLE",
+    /**
+     * Access to the Google account was lost. The site owner needs to connect
+     * again.
+     */
+    PERMISSION_REVOKED = "PERMISSION_REVOKED",
+    /** Google was still rate limiting after the queue used up its retries. */
+    RATE_LIMIT_EXHAUSTED = "RATE_LIMIT_EXHAUSTED",
+    /**
+     * The change may or may not have reached Google, and the queue chose not to
+     * risk a duplicate by trying again. Additions only.
+     *
+     * Unlike every other reason here, this doesn't say anything is wrong with the
+     * photo. It says the outcome couldn't be confirmed. Word it for the site owner
+     * that way: "we couldn't confirm this photo was added", not "this photo was
+     * rejected".
+     */
+    UPLOAD_UNVERIFIED = "UPLOAD_UNVERIFIED"
+}
+/** @enumType */
+type MediaUploadFailureReasonWithLiterals = MediaUploadFailureReason | 'IMAGE_TOO_SMALL' | 'ASPECT_RATIO_REJECTED' | 'FORMAT_UNSUPPORTED' | 'SOURCE_UNREACHABLE' | 'PERMISSION_REVOKED' | 'RATE_LIMIT_EXHAUSTED' | 'UPLOAD_UNVERIFIED';
+interface BulkCreateMediaUploadsRequest {
+    /**
+     * Photo changes to queue. All must share one `locationId` and one `operation`.
+     *
+     * Per item set `locationId`, `operation`, `slotKey`, and then either
+     * `sourceUrl`, `category` and `format` to add, or `mediaKey` to remove. Every
+     * other field is assigned by the server and ignored if you send it.
+     *
+     * Up to 52 items: 50 gallery photos plus a logo and a cover.
+     * @minSize 1
+     * @maxSize 52
+     */
+    mediaUploads: MediaUpload[];
+    /** Whether to return each queued item in `results.item`. */
+    returnEntity?: boolean;
+}
+interface BulkCreateMediaUploadsResponse {
+    /**
+     * Results in the order the items were sent. An item that was already queued is
+     * reported as a success carrying the existing item's `id`.
+     * @minSize 1
+     * @maxSize 52
+     */
+    results?: BulkCreateMediaUploadResult[];
+    /** How many items succeeded and failed. */
+    bulkActionMetadata?: BulkActionMetadata;
+}
+interface ItemMetadata {
+    /**
+     * Item ID. Provided only whenever possible. For example, `itemId` can't be provided when item creation has failed.
+     * @format GUID
+     */
+    _id?: string | null;
+    /** Index of the item within the request array. Allows for correlation between request and response items. */
+    originalIndex?: number;
+    /** Whether the requested action for this item was successful. When `false`, the `error` field is returned. */
+    success?: boolean;
+    /** Details about the error in case of failure. */
+    error?: ApplicationError;
+}
+interface ApplicationError {
+    /** Error code. */
+    code?: string;
+    /** Description of the error. */
+    description?: string;
+    /** Data related to the error. */
+    data?: Record<string, any> | null;
+}
+interface BulkCreateMediaUploadResult {
+    /** Whether this item was queued, and why not if it wasn't. */
+    itemMetadata?: ItemMetadata;
+    /** The queued item. Returned only when `returnEntity` is `true`. */
+    item?: MediaUpload;
+}
+interface BulkActionMetadata {
+    /** Number of items that were successfully processed. */
+    totalSuccesses?: number;
+    /** Number of items that couldn't be processed. */
+    totalFailures?: number;
+    /** Number of failures without details because detailed failure threshold was exceeded. */
+    undetailedFailures?: number;
+}
+interface ListMediaUploadsRequest {
+    /**
+     * ID of the location. This is Google's location identifier.
+     * @minLength 1
+     * @maxLength 255
+     */
+    locationId: string;
+}
+interface ListMediaUploadsResponse {
+    /**
+     * Every outstanding change for the location, in the order it will be applied.
+     * An empty list means the queue finished and nothing failed.
+     *
+     * Never paged and never truncated. If the set is somehow too large to return,
+     * the call fails with `FAILED_PRECONDITION` rather than returning part of it.
+     * @maxSize 500
+     */
+    mediaUploads?: MediaUpload[];
+}
+interface DismissMediaUploadFailuresRequest {
+    /**
+     * ID of the location. This is Google's location identifier.
+     * @minLength 1
+     * @maxLength 255
+     */
+    locationId: string;
+}
+interface DismissMediaUploadFailuresResponse {
+    /** How many failed changes were cleared. */
+    dismissedCount?: number;
+}
+/** @docsIgnore */
+type BulkCreateMediaUploadsApplicationErrors = {
+    code?: 'MEDIA_UPLOAD_INVALID_SOURCE_URL';
+    description?: string;
+    data?: Record<string, any>;
+};
+/** @docsIgnore */
+type ListMediaUploadsApplicationErrors = {
+    code?: 'MEDIA_UPLOAD_LIST_TOO_LARGE';
+    description?: string;
+    data?: Record<string, any>;
+};
+/**
+ * Queues photo changes for one location and returns without calling Google.
+ *
+ * Every item must target the same `locationId`, and one call has to be either
+ * all additions or all removals. Send two calls to do both.
+ *
+ * To add a photo, set `slotKey`, `sourceUrl`, `category` and `format`. To
+ * remove one, set `slotKey` and `mediaKey`. Everything else is assigned by the
+ * server.
+ *
+ * `sourceUrl` has to stay reachable well after this call returns, not just
+ * until it does. Google fetches the image when the queue reaches it, which may
+ * be minutes later, and a failure report renders the same URL as a thumbnail
+ * possibly weeks later.
+ *
+ * Queuing clears the location's previous failures. Every failed item for the
+ * location goes, not just the ones matching what you're sending, so a site
+ * owner only ever sees the most recent set and retrying failures is just
+ * another call to this method carrying those items.
+ *
+ * That clearing isn't scoped to you. If another app manages the same location,
+ * queuing here discards failures it may not have read yet, and vice versa. Read
+ * List Media Uploads before queuing if you need to preserve them.
+ *
+ * Duplicates are dropped rather than queued twice, so a double click or a
+ * client retry won't add the same photo twice. An item that's already queued
+ * comes back as a success carrying the existing item's `id`. Google doesn't
+ * deduplicate by URL itself, so this is what protects you from a double post.
+ *
+ * The server decides the order, not the order you send. Every removal is
+ * applied before any addition, because Google rejects new photos on a profile
+ * that's already at its limit. Additions then go logo, cover, and gallery in
+ * the order given.
+ *
+ * Errors, and in every case nothing is queued:
+ * - `NOT_FOUND`: the location isn't recorded for this site.
+ * - `INVALID_ARGUMENT`: items span more than one location, an item has no
+ * operation set, additions and removals are mixed in one call, an addition
+ * has no `sourceUrl`, or a removal has no `mediaKey`.
+ * - `MEDIA_UPLOAD_INVALID_SOURCE_URL`: an addition's `sourceUrl` isn't an
+ * absolute `http` or `https` URL with a host. Checked here rather than left
+ * to fail against Google minutes later.
+ * @param mediaUploads - Photo changes to queue. All must share one `locationId` and one `operation`.
+ *
+ * Per item set `locationId`, `operation`, `slotKey`, and then either
+ * `sourceUrl`, `category` and `format` to add, or `mediaKey` to remove. Every
+ * other field is assigned by the server and ignored if you send it.
+ *
+ * Up to 52 items: 50 gallery photos plus a logo and a cover.
+ * @public
+ * @documentationMaturity preview
+ * @requiredField mediaUploads
+ * @permissionId gbp:location:v1:media_upload:bulk_create_media_uploads
+ * @applicableIdentity APP
+ * @fqn wix.gbp.location.v1.MediaUploadService.BulkCreateMediaUploads
+ */
+declare function bulkCreateMediaUploads(mediaUploads: MediaUpload[], options?: BulkCreateMediaUploadsOptions): Promise<NonNullablePaths<BulkCreateMediaUploadsResponse, `results` | `results.${number}.itemMetadata.originalIndex` | `results.${number}.itemMetadata.success` | `results.${number}.itemMetadata.error.code` | `results.${number}.itemMetadata.error.description` | `results.${number}.item._id` | `results.${number}.item.locationId` | `results.${number}.item.batchId` | `results.${number}.item.slotKey` | `results.${number}.item.sourceUrl` | `results.${number}.item.category` | `results.${number}.item.format` | `results.${number}.item.operation` | `results.${number}.item.sequence` | `results.${number}.item.state` | `results.${number}.item.attempts` | `results.${number}.item.mediaKey` | `results.${number}.item.failure.reason` | `results.${number}.item.revision` | `bulkActionMetadata.totalSuccesses` | `bulkActionMetadata.totalFailures` | `bulkActionMetadata.undetailedFailures`, 6> & {
+    __applicationErrorsType?: BulkCreateMediaUploadsApplicationErrors;
+}>;
+interface BulkCreateMediaUploadsOptions {
+    /** Whether to return each queued item in `results.item`. */
+    returnEntity?: boolean;
+}
+/**
+ * Retrieves the photo changes still queued or failed for a location.
+ *
+ * This is how you follow an asynchronous submission, since there's no
+ * completion callback. Read the response as a whole rather than item by item:
+ *
+ * - Anything `PENDING` or `UPLOADING` means the queue is still working. Don't
+ * report results yet.
+ * - Only `FAILED` items means the queue finished and those items didn't make
+ * it.
+ * - An empty response means nothing is outstanding for this location.
+ *
+ * Read that last one carefully, because it's weaker than it looks. It tells you
+ * the queue is empty, not that a particular submission succeeded. A successful
+ * change leaves nothing behind, and so does a failure that's been cleared, and
+ * the two are indistinguishable afterwards. Google's own media list is the
+ * record of what's actually live, so confirm against List Media rather than
+ * inferring success from an empty queue.
+ *
+ * Failures are cleared for the whole location by the next call to Bulk Create
+ * Media Uploads, whoever makes it. If more than one app manages the same
+ * location, one app queuing a change clears failures the other hasn't read yet.
+ * Read failures before queuing again, and don't treat an empty response as
+ * proof that your own submission worked.
+ *
+ * You can also use this to show a gallery matching what the site owner asked
+ * for while the queue is still working, because Google's list lags behind in
+ * both directions. Count only changes still on their way, since a `FAILED`
+ * addition never reached Google:
+ *
+ * ```
+ * gallery = Google's media list
+ * + additions still PENDING or UPLOADING
+ * - removals still PENDING or UPLOADING
+ * ```
+ *
+ * The response is never paged and never truncated. It returns the complete set
+ * or fails with `FAILED_PRECONDITION`.
+ * @param locationId - ID of the location. This is Google's location identifier.
+ * @public
+ * @documentationMaturity preview
+ * @requiredField locationId
+ * @permissionId gbp:location:v1:media_upload:list_media_uploads
+ * @applicableIdentity APP
+ * @fqn wix.gbp.location.v1.MediaUploadService.ListMediaUploads
+ */
+declare function listMediaUploads(locationId: string): Promise<NonNullablePaths<ListMediaUploadsResponse, `mediaUploads` | `mediaUploads.${number}._id` | `mediaUploads.${number}.locationId` | `mediaUploads.${number}.batchId` | `mediaUploads.${number}.slotKey` | `mediaUploads.${number}.sourceUrl` | `mediaUploads.${number}.category` | `mediaUploads.${number}.format` | `mediaUploads.${number}.operation` | `mediaUploads.${number}.sequence` | `mediaUploads.${number}.state` | `mediaUploads.${number}.attempts` | `mediaUploads.${number}.mediaKey` | `mediaUploads.${number}.failure.reason` | `mediaUploads.${number}.revision`, 5> & {
+    __applicationErrorsType?: ListMediaUploadsApplicationErrors;
+}>;
+/**
+ * Clears a location's failed photo changes, leaving queued ones alone.
+ *
+ * Failures are otherwise kept until the next submission for that location
+ * replaces them, so this is how a site owner dismisses a photo that's never
+ * going to succeed.
+ *
+ * `dismissedCount` reports how many were cleared.
+ * @param locationId - ID of the location. This is Google's location identifier.
+ * @public
+ * @documentationMaturity preview
+ * @requiredField locationId
+ * @permissionId gbp:location:v1:media_upload:dismiss_media_upload_failures
+ * @applicableIdentity APP
+ * @fqn wix.gbp.location.v1.MediaUploadService.DismissMediaUploadFailures
+ */
+declare function dismissMediaUploadFailures(locationId: string): Promise<NonNullablePaths<DismissMediaUploadFailuresResponse, `dismissedCount`, 2>>;
+
+export { type ApplicationError, type BulkActionMetadata, type BulkCreateMediaUploadResult, type BulkCreateMediaUploadsApplicationErrors, type BulkCreateMediaUploadsOptions, type BulkCreateMediaUploadsRequest, type BulkCreateMediaUploadsResponse, type DismissMediaUploadFailuresRequest, type DismissMediaUploadFailuresResponse, type ItemMetadata, type ListMediaUploadsApplicationErrors, type ListMediaUploadsRequest, type ListMediaUploadsResponse, MediaCategory, type MediaCategoryWithLiterals, MediaFormat, type MediaFormatWithLiterals, type MediaUpload, type MediaUploadFailure, MediaUploadFailureReason, type MediaUploadFailureReasonWithLiterals, MediaUploadOperation, type MediaUploadOperationWithLiterals, MediaUploadState, type MediaUploadStateWithLiterals, bulkCreateMediaUploads, dismissMediaUploadFailures, listMediaUploads };