swift-sdk/Sources/Hanzo/APIs/TranslateAPI.swift

//
// TranslateAPI.swift
//
// Generated by openapi-generator
// https://openapi-generator.tech
//

import Foundation

open class TranslateAPI {

    /**
     List returns the org's own translation-memory entries, newest first, optionally narrowed to one target language and/or one position on the review ladder.
     
     - parameter target: (query) Target narrows to one target language tag (BCP-47, e.g. \"es\" or \"pt-BR\"). (optional)
     - parameter state: (query) State narrows to one position on the review ladder: machine, suggested, approved or published. (optional)
     - parameter limit: (query) Limit caps the rows returned. Non-positive or unparseable means the server default (200); the ceiling is 1000. (optional)
     - parameter apiConfiguration: The configuration for the http request.
     - returns: MemoryPage
     */
    @available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
    open class func getTranslateMemory(target: String? = nil, state: String? = nil, limit: Int64? = nil, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) async throws(ErrorResponse) -> MemoryPage {
        return try await getTranslateMemoryWithRequestBuilder(target: target, state: state, limit: limit, apiConfiguration: apiConfiguration).execute().body
    }

    /**
     List returns the org's own translation-memory entries, newest first, optionally narrowed to one target language and/or one position on the review ladder.
     - GET /v1/translate/memory
     - List returns the org's own translation-memory entries, newest first, optionally narrowed to one target language and/or one position on the review ladder. It is the review lane's read: what a human reviewer works through.  The org is ALWAYS the validated principal's org, never a request field, so one tenant can never read another's memory — the entries hold customer source text.
     - Bearer Token:
       - type: http
       - name: bearer
     - parameter target: (query) Target narrows to one target language tag (BCP-47, e.g. \"es\" or \"pt-BR\"). (optional)
     - parameter state: (query) State narrows to one position on the review ladder: machine, suggested, approved or published. (optional)
     - parameter limit: (query) Limit caps the rows returned. Non-positive or unparseable means the server default (200); the ceiling is 1000. (optional)
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RequestBuilder<MemoryPage> 
     */
    open class func getTranslateMemoryWithRequestBuilder(target: String? = nil, state: String? = nil, limit: Int64? = nil, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) -> RequestBuilder<MemoryPage> {
        let localVariablePath = "/v1/translate/memory"
        let localVariableURLString = apiConfiguration.basePath + localVariablePath
        let localVariableParameters: [String: any Sendable]? = nil

        var localVariableUrlComponents = URLComponents(string: localVariableURLString)
        localVariableUrlComponents?.queryItems = APIHelper.mapValuesToQueryItems([
            "target": (wrappedValue: target?.asParameter(codableHelper: apiConfiguration.codableHelper), isExplode: true),
            "state": (wrappedValue: state?.asParameter(codableHelper: apiConfiguration.codableHelper), isExplode: true),
            "limit": (wrappedValue: limit?.asParameter(codableHelper: apiConfiguration.codableHelper), isExplode: true),
        ])

        let localVariableNillableHeaders: [String: (any Sendable)?] = [
            :
        ]

        let localVariableHeaderParameters = APIHelper.rejectNilHeaders(localVariableNillableHeaders)

        let localVariableRequestBuilder: RequestBuilder<MemoryPage>.Type = apiConfiguration.requestBuilderFactory.getBuilder()

        return localVariableRequestBuilder.init(method: "GET", URLString: (localVariableUrlComponents?.string ?? localVariableURLString), parameters: localVariableParameters, headers: localVariableHeaderParameters, requiresAuthentication: true, apiConfiguration: apiConfiguration)
    }

    /**
     Translate a string or a batch into one target language
     
     - parameter apiConfiguration: The configuration for the http request.
     - returns: Void
     */
    @available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
    open class func postTranslate(apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) async throws(ErrorResponse) {
        return try await postTranslateWithRequestBuilder(apiConfiguration: apiConfiguration).execute().body
    }

    /**
     Translate a string or a batch into one target language
     - POST /v1/translate
     - Returns one translation per input string, in input order, each carrying where it sits on the review ladder and whether it came from your memory rather than an engine — plus a usage block of REAL counts (strings, cached, translated, and the source characters that actually reached an engine). Send `text` for one string or `batch` for many, never both. When you name no `source`, the detected one is reported back.  THE TRANSLATION MEMORY IS CONSULTED FIRST AND IT IS NORMATIVE, NOT A CACHE. Every string keys on (source text, target, glossary version, tier); a hit is returned VERBATIM and never re-translated, which is what makes a locale rebuild idempotent under a non-deterministic model and the bill proportional to what actually changed. Misses go to the engine and are written back at state `machine`. Editing a glossary term changes the key, so a stale rendering can never be served.  IT CANNOT TRAMPLE REVIEWED WORK. A write from this route may create an entry or refresh one still at `machine`, and nothing else — a string a human moved to approved or published through the memory review lane survives every rebuild, and comes back here unchanged. The memory is the caller's OWN org's, a separate store per org: the source text you send is customer content and lands nowhere else. Read it back or review it at /v1/translate/memory.  `tier` picks the engine and defaults to quality — the model plane, which carries context, terminology and tone, and which bills its own tokens, so nothing is charged twice here. `bulk` is the high-volume engine and is metered HERE, on the source characters that reached it: a fully-cached rebuild reports zero characters and costs zero. BULK NEVER FALLS BACK TO QUALITY — on a deployment that does not serve it the answer is 503 for that tier, so a caller is never quietly served, or charged, at a tier it did not ask for. A bulk request beyond its balance is refused with the nested {\"error\":{\"code\",\"message\"}} body at 402/503.  `target` IS CHECKED FOR SHAPE, NOT FOR SUPPORT: anything BCP-47-shaped is accepted (`es`, `pt-BR`), anything else is 400. There is no unsupported-language error — a well-formed tag no engine can actually render is passed straight through, and whatever comes back is what gets stored and returned. `format` (text, html, markdown) tells the engine what markup to preserve; `glossary` fixes terms verbatim.  Requires a validated principal — 401 without one, and the org is always that principal's. At most 512 strings per call and 32768 characters per string; an engine that fails or answers a reply that does not cover every input is 502, and nothing is stored.
     - Bearer Token:
       - type: http
       - name: bearer
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RequestBuilder<Void> 
     */
    open class func postTranslateWithRequestBuilder(apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) -> RequestBuilder<Void> {
        let localVariablePath = "/v1/translate"
        let localVariableURLString = apiConfiguration.basePath + localVariablePath
        let localVariableParameters: [String: any Sendable]? = nil

        let localVariableUrlComponents = URLComponents(string: localVariableURLString)

        let localVariableNillableHeaders: [String: (any Sendable)?] = [
            :
        ]

        let localVariableHeaderParameters = APIHelper.rejectNilHeaders(localVariableNillableHeaders)

        let localVariableRequestBuilder: RequestBuilder<Void>.Type = apiConfiguration.requestBuilderFactory.getNonDecodableBuilder()

        return localVariableRequestBuilder.init(method: "POST", URLString: (localVariableUrlComponents?.string ?? localVariableURLString), parameters: localVariableParameters, headers: localVariableHeaderParameters, requiresAuthentication: true, apiConfiguration: apiConfiguration)
    }

    /**
     Review records a human decision on one translation-memory entry, and returns the entry as stored.
     
     - parameter reviewRequest: (body)  
     - parameter apiConfiguration: The configuration for the http request.
     - returns: MemoryEntry
     */
    @available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
    open class func putTranslateMemory(reviewRequest: ReviewRequest, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) async throws(ErrorResponse) -> MemoryEntry {
        return try await putTranslateMemoryWithRequestBuilder(reviewRequest: reviewRequest, apiConfiguration: apiConfiguration).execute().body
    }

    /**
     Review records a human decision on one translation-memory entry, and returns the entry as stored.
     - PUT /v1/translate/memory
     - Review records a human decision on one translation-memory entry, and returns the entry as stored. A human write always wins over the stored value, and once it lands at approved or published no machine write can move it again — which is what makes a locale rebuild safe to run against reviewed work.  The org is ALWAYS the validated principal's org, never a request field, so a review can only ever land in the caller's own memory.
     - Bearer Token:
       - type: http
       - name: bearer
     - parameter reviewRequest: (body)  
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RequestBuilder<MemoryEntry> 
     */
    open class func putTranslateMemoryWithRequestBuilder(reviewRequest: ReviewRequest, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) -> RequestBuilder<MemoryEntry> {
        let localVariablePath = "/v1/translate/memory"
        let localVariableURLString = apiConfiguration.basePath + localVariablePath
        let localVariableParameters = JSONEncodingHelper.encodingParameters(forEncodableObject: reviewRequest, codableHelper: apiConfiguration.codableHelper)

        let localVariableUrlComponents = URLComponents(string: localVariableURLString)

        let localVariableNillableHeaders: [String: (any Sendable)?] = [
            "Content-Type": "application/json",
        ]

        let localVariableHeaderParameters = APIHelper.rejectNilHeaders(localVariableNillableHeaders)

        let localVariableRequestBuilder: RequestBuilder<MemoryEntry>.Type = apiConfiguration.requestBuilderFactory.getBuilder()

        return localVariableRequestBuilder.init(method: "PUT", URLString: (localVariableUrlComponents?.string ?? localVariableURLString), parameters: localVariableParameters, headers: localVariableHeaderParameters, requiresAuthentication: true, apiConfiguration: apiConfiguration)
    }
}