gt-sanity 0.0.5

package/LICENSE.md

@@ -0,0 +1,138 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2025 General Translation, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+## Additional Code
+
+The following files of the Software are adapted from https://github.com/sanity-io/sanity-translations-tab.
+These portions are licensed under the license of the original software, listed below.
+
+- src/components/\*\*
+- src/configuration/\*\*
+- src/hooks/\*\*
+- src/types.ts
+- src/utils/\*\*
+
+MIT License
+
+Copyright (c) 2025 Sanity.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @generaltranslation/sanity
+
+> This is a **Sanity Studio v3** plugin.
+
+## Installation
+
+```sh
+npm install @generaltranslation/sanity
+```
+
+Then, create a [GT project](https://generaltranslation.com/dashboard) and get a production API key and project ID.
+
+In your Studio folder, create a file called `populateSecrets.js` with the following content:
+
+```javascript
+// ./populateSecrets.js
+// Do not commit this file to your repository
+
+import { getCliClient } from 'sanity/cli';
+
+const client = getCliClient({ apiVersion: '2025-09-15' });
+
+client.createOrReplace({
+  // The `.` in this _id will ensure the document is private
+  // even in a public dataset!
+  _id: 'generaltranslation.secrets',
+  _type: 'generaltranslationSettings',
+  // replace these with your values
+  project: '<GT_PROJECT_ID>',
+  secret: '<GT_API_KEY>',
+});
+```
+
+Run the script:
+
+```sh
+npx sanity exec populateSecrets.js --with-user-token
+```
+
+Verify that the document was created using the Vision Tool in the Studio and query `*[_id == 'generaltranslation.secrets']`. Note: If you have multiple datasets, you'll have to do this across all of them.
+
+If the document was found in your dataset(s), delete `populateSecrets.js`.
+
+If you have concerns about this being exposed to authenticated users of your studio, you can control access to this path with [role-based access control](https://www.sanity.io/docs/access-control).
+
+## Usage
+
+Add it as a plugin in `sanity.config.ts` (or .js):
+
+```ts
+import { defineConfig } from 'sanity';
+import { gtPlugin } from '@generaltranslation/sanity';
+
+export default defineConfig({
+  //...
+  plugins: [
+    gtPlugin({
+      sourceLocale: 'en',
+      // Specify your locales here
+      locales: ['es', 'fr'],
+    }),
+  ],
+});
+```
+
+Add the Translation View to your document structure:
+
+```ts
+// ./structure.ts
+import type { DefaultDocumentNodeResolver } from 'sanity/structure';
+import { TranslationsTab } from '@generaltranslation/sanity';
+import { defaultDocumentLevelConfig } from '@generaltranslation/sanity';
+export const defaultDocumentNode: DefaultDocumentNodeResolver = (
+  S,
+  { schemaType }
+) => {
+  // Replace 'translatable' with your schema type(s)
+  if (schemaType === 'translatable') {
+    return S.document().views([
+      S.view.form(),
+      S.view
+        .component(TranslationsTab)
+        .title('General Translation')
+        .options(defaultDocumentLevelConfig),
+    ]);
+  }
+};
+```
+
+## License
+
+[FSL-1.1-ALv2](LICENSE.md) © General Translation, Inc.
+
+## Develop & test
+
+This plugin uses [@sanity/plugin-kit](https://github.com/sanity-io/plugin-kit)
+with default configuration for build & watch scripts.
+
+See [Testing a plugin in Sanity Studio](https://github.com/sanity-io/plugin-kit#testing-a-plugin-in-sanity-studio)
+on how to run this plugin with hotreload in the studio.

package/dist/index.d.mts

@@ -0,0 +1,241 @@
+import { BaseDocumentDeserializer } from 'sanity-naive-html-serializer';
+import { BaseDocumentMerger } from 'sanity-naive-html-serializer';
+import { BaseDocumentSerializer } from 'sanity-naive-html-serializer';
+import { CustomMapping } from 'generaltranslation/types';
+import { customSerializers } from 'sanity-naive-html-serializer';
+import { defaultStopTypes } from 'sanity-naive-html-serializer';
+import { DeserializerRule } from '@sanity/block-tools';
+import { JSX } from 'react';
+import { Plugin as Plugin_2 } from 'sanity';
+import { PortableTextTypeComponent } from '@portabletext/to-html';
+import { SanityClient } from 'sanity';
+import { SanityDocument } from 'sanity';
+import { Schema } from 'sanity';
+import { SerializedDocument } from 'sanity-naive-html-serializer';
+import { TypedObject } from 'sanity';
+
+export declare interface Adapter {
+  getLocales: (secrets: Secrets | null) => Promise<TranslationLocale[]>;
+  getTranslationTask: (
+    document: GTFile,
+    secrets: Secrets | null
+  ) => Promise<TranslationTask>;
+  createTask: (
+    documentInfo: GTFile,
+    serializedDocument: GTSerializedDocument,
+    localeIds: string[],
+    secrets: Secrets | null,
+    workflowUid?: string,
+    callbackUrl?: string
+  ) => Promise<TranslationTask>;
+  getTranslation: (
+    document: GTFile,
+    localeId: string,
+    secrets: Secrets | null
+  ) => Promise<any | null>;
+}
+
+export { BaseDocumentDeserializer };
+
+export { BaseDocumentMerger };
+
+export { BaseDocumentSerializer };
+
+declare interface ConfigOptions {
+  adapter: Adapter;
+  secretsNamespace: string | null;
+  exportForTranslation: (
+    docInfo: GTFile,
+    context: TranslationFunctionContext
+  ) => Promise<GTSerializedDocument>;
+  importTranslation: (
+    docInfo: GTFile,
+    localeId: string,
+    doc: string,
+    context: TranslationFunctionContext
+  ) => Promise<void>;
+}
+
+export { customSerializers };
+
+export declare const defaultDocumentLevelConfig: ConfigOptions;
+
+export declare const defaultFieldLevelConfig: ConfigOptions;
+
+export { defaultStopTypes };
+
+export declare const documentLevelPatch: (
+  docInfo: GTFile,
+  translatedFields: SanityDocument,
+  localeId: string,
+  client: SanityClient,
+  languageField?: string,
+  mergeWithTargetLocale?: boolean
+) => Promise<void>;
+
+export declare type ExportForTranslation = (
+  documentInfo: GTFile,
+  context: TranslationFunctionContext,
+  serializationOptions?: {
+    additionalStopTypes?: string[];
+    additionalSerializers?: Record<
+      string,
+      PortableTextTypeComponent | undefined
+    >;
+  },
+  languageField?: string
+) => Promise<GTSerializedDocument>;
+
+export declare const fieldLevelPatch: (
+  docInfo: GTFile,
+  translatedFields: SanityDocument,
+  localeId: string,
+  client: SanityClient,
+  mergeWithTargetLocale?: boolean
+) => Promise<void>;
+
+export declare const findLatestDraft: (
+  documentId: string,
+  client: SanityClient
+) => Promise<SanityDocument>;
+
+export declare const GTAdapter: Adapter;
+
+declare type GTFile = {
+  documentId: string;
+  versionId?: string;
+};
+
+/**
+ * Usage in `sanity.config.ts` (or .js)
+ *
+ * ```ts
+ * import {defineConfig} from 'sanity'
+ * import {gtPlugin} from '@generaltranslation/sanity'
+ *
+ * export default defineConfig({
+ *   // ...
+ *   plugins: [gtPlugin()],
+ * })
+ * ```
+ */
+export declare const gtPlugin: Plugin_2<
+  Omit<
+    {
+      apiKey?: string;
+      devApiKey?: string;
+      sourceLocale?: string;
+      targetLocale?: string;
+      locales?: string[];
+      projectId?: string;
+      baseUrl?: string;
+      customMapping?: CustomMapping;
+    },
+    'locales'
+  > & {
+    locales: string[];
+  }
+>;
+
+declare type GTSerializedDocument = Omit<SerializedDocument, 'name'> & GTFile;
+
+export declare type ImportTranslation = (
+  documentInfo: GTFile,
+  localeId: string,
+  document: string,
+  context: TranslationFunctionContext,
+  serializationOptions?: {
+    additionalDeserializers?: Record<
+      string,
+      (value: HTMLElement) => TypedObject
+    >;
+    additionalBlockDeserializers?: DeserializerRule[];
+  },
+  languageField?: string,
+  mergeWithTargetLocale?: boolean
+) => Promise<void>;
+
+export declare const legacyDocumentLevelConfig: ConfigOptions;
+
+export declare const legacyDocumentLevelPatch: (
+  docInfo: GTFile,
+  translatedFields: SanityDocument,
+  localeId: string,
+  client: SanityClient
+) => Promise<void>;
+
+export declare type Secrets = {
+  organization: string;
+  project: string;
+  token?: string;
+  secret?: string;
+  username?: string;
+  password?: string;
+  proxy?: string;
+};
+
+export { SerializedDocument };
+
+export declare interface TranslationFunctionContext {
+  client: SanityClient;
+  schema: Schema;
+}
+
+declare type TranslationLocale = {
+  localeId: string;
+  description: string;
+  enabled?: boolean;
+};
+
+export declare const TranslationsTab: (
+  props: TranslationTabProps
+) => JSX.Element;
+
+export declare type TranslationsTabConfigOptions = {
+  adapter: Adapter;
+  secretsNamespace: string | null;
+  exportForTranslation: ExportForTranslation;
+  importTranslation: ImportTranslation;
+  serializationOptions?: {
+    additionalStopTypes?: string[];
+    additionalSerializers?: Record<
+      string,
+      PortableTextTypeComponent | undefined
+    >;
+    additionalDeserializers?: Record<
+      string,
+      (value: HTMLElement) => TypedObject
+    >;
+    additionalBlockDeserializers?: DeserializerRule[];
+  };
+  workflowOptions?: WorkflowIdentifiers[];
+  localeIdAdapter?: (id: string) => string;
+  languageField?: string;
+  callbackUrl?: string;
+  mergeWithTargetLocale?: boolean;
+};
+
+declare type TranslationTabProps = {
+  document: {
+    displayed: SanityDocument;
+  };
+  options: TranslationsTabConfigOptions;
+};
+
+declare type TranslationTask = {
+  document: GTFile;
+  locales: TranslationTaskLocaleStatus[];
+  linkToVendorTask?: string;
+};
+
+declare type TranslationTaskLocaleStatus = {
+  localeId: string;
+  progress: number;
+};
+
+declare type WorkflowIdentifiers = {
+  workflowUid: string;
+  workflowName: string;
+};
+
+export {};

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+import { BaseDocumentDeserializer } from 'sanity-naive-html-serializer';
+import { BaseDocumentMerger } from 'sanity-naive-html-serializer';
+import { BaseDocumentSerializer } from 'sanity-naive-html-serializer';
+import { CustomMapping } from 'generaltranslation/types';
+import { customSerializers } from 'sanity-naive-html-serializer';
+import { defaultStopTypes } from 'sanity-naive-html-serializer';
+import { DeserializerRule } from '@sanity/block-tools';
+import { JSX } from 'react';
+import { Plugin as Plugin_2 } from 'sanity';
+import { PortableTextTypeComponent } from '@portabletext/to-html';
+import { SanityClient } from 'sanity';
+import { SanityDocument } from 'sanity';
+import { Schema } from 'sanity';
+import { SerializedDocument } from 'sanity-naive-html-serializer';
+import { TypedObject } from 'sanity';
+
+export declare interface Adapter {
+  getLocales: (secrets: Secrets | null) => Promise<TranslationLocale[]>;
+  getTranslationTask: (
+    document: GTFile,
+    secrets: Secrets | null
+  ) => Promise<TranslationTask>;
+  createTask: (
+    documentInfo: GTFile,
+    serializedDocument: GTSerializedDocument,
+    localeIds: string[],
+    secrets: Secrets | null,
+    workflowUid?: string,
+    callbackUrl?: string
+  ) => Promise<TranslationTask>;
+  getTranslation: (
+    document: GTFile,
+    localeId: string,
+    secrets: Secrets | null
+  ) => Promise<any | null>;
+}
+
+export { BaseDocumentDeserializer };
+
+export { BaseDocumentMerger };
+
+export { BaseDocumentSerializer };
+
+declare interface ConfigOptions {
+  adapter: Adapter;
+  secretsNamespace: string | null;
+  exportForTranslation: (
+    docInfo: GTFile,
+    context: TranslationFunctionContext
+  ) => Promise<GTSerializedDocument>;
+  importTranslation: (
+    docInfo: GTFile,
+    localeId: string,
+    doc: string,
+    context: TranslationFunctionContext
+  ) => Promise<void>;
+}
+
+export { customSerializers };
+
+export declare const defaultDocumentLevelConfig: ConfigOptions;
+
+export declare const defaultFieldLevelConfig: ConfigOptions;
+
+export { defaultStopTypes };
+
+export declare const documentLevelPatch: (
+  docInfo: GTFile,
+  translatedFields: SanityDocument,
+  localeId: string,
+  client: SanityClient,
+  languageField?: string,
+  mergeWithTargetLocale?: boolean
+) => Promise<void>;
+
+export declare type ExportForTranslation = (
+  documentInfo: GTFile,
+  context: TranslationFunctionContext,
+  serializationOptions?: {
+    additionalStopTypes?: string[];
+    additionalSerializers?: Record<
+      string,
+      PortableTextTypeComponent | undefined
+    >;
+  },
+  languageField?: string
+) => Promise<GTSerializedDocument>;
+
+export declare const fieldLevelPatch: (
+  docInfo: GTFile,
+  translatedFields: SanityDocument,
+  localeId: string,
+  client: SanityClient,
+  mergeWithTargetLocale?: boolean
+) => Promise<void>;
+
+export declare const findLatestDraft: (
+  documentId: string,
+  client: SanityClient
+) => Promise<SanityDocument>;
+
+export declare const GTAdapter: Adapter;
+
+declare type GTFile = {
+  documentId: string;
+  versionId?: string;
+};
+
+/**
+ * Usage in `sanity.config.ts` (or .js)
+ *
+ * ```ts
+ * import {defineConfig} from 'sanity'
+ * import {gtPlugin} from '@generaltranslation/sanity'
+ *
+ * export default defineConfig({
+ *   // ...
+ *   plugins: [gtPlugin()],
+ * })
+ * ```
+ */
+export declare const gtPlugin: Plugin_2<
+  Omit<
+    {
+      apiKey?: string;
+      devApiKey?: string;
+      sourceLocale?: string;
+      targetLocale?: string;
+      locales?: string[];
+      projectId?: string;
+      baseUrl?: string;
+      customMapping?: CustomMapping;
+    },
+    'locales'
+  > & {
+    locales: string[];
+  }
+>;
+
+declare type GTSerializedDocument = Omit<SerializedDocument, 'name'> & GTFile;
+
+export declare type ImportTranslation = (
+  documentInfo: GTFile,
+  localeId: string,
+  document: string,
+  context: TranslationFunctionContext,
+  serializationOptions?: {
+    additionalDeserializers?: Record<
+      string,
+      (value: HTMLElement) => TypedObject
+    >;
+    additionalBlockDeserializers?: DeserializerRule[];
+  },
+  languageField?: string,
+  mergeWithTargetLocale?: boolean
+) => Promise<void>;
+
+export declare const legacyDocumentLevelConfig: ConfigOptions;
+
+export declare const legacyDocumentLevelPatch: (
+  docInfo: GTFile,
+  translatedFields: SanityDocument,
+  localeId: string,
+  client: SanityClient
+) => Promise<void>;
+
+export declare type Secrets = {
+  organization: string;
+  project: string;
+  token?: string;
+  secret?: string;
+  username?: string;
+  password?: string;
+  proxy?: string;
+};
+
+export { SerializedDocument };
+
+export declare interface TranslationFunctionContext {
+  client: SanityClient;
+  schema: Schema;
+}
+
+declare type TranslationLocale = {
+  localeId: string;
+  description: string;
+  enabled?: boolean;
+};
+
+export declare const TranslationsTab: (
+  props: TranslationTabProps
+) => JSX.Element;
+
+export declare type TranslationsTabConfigOptions = {
+  adapter: Adapter;
+  secretsNamespace: string | null;
+  exportForTranslation: ExportForTranslation;
+  importTranslation: ImportTranslation;
+  serializationOptions?: {
+    additionalStopTypes?: string[];
+    additionalSerializers?: Record<
+      string,
+      PortableTextTypeComponent | undefined
+    >;
+    additionalDeserializers?: Record<
+      string,
+      (value: HTMLElement) => TypedObject
+    >;
+    additionalBlockDeserializers?: DeserializerRule[];
+  };
+  workflowOptions?: WorkflowIdentifiers[];
+  localeIdAdapter?: (id: string) => string;
+  languageField?: string;
+  callbackUrl?: string;
+  mergeWithTargetLocale?: boolean;
+};
+
+declare type TranslationTabProps = {
+  document: {
+    displayed: SanityDocument;
+  };
+  options: TranslationsTabConfigOptions;
+};
+
+declare type TranslationTask = {
+  document: GTFile;
+  locales: TranslationTaskLocaleStatus[];
+  linkToVendorTask?: string;
+};
+
+declare type TranslationTaskLocaleStatus = {
+  localeId: string;
+  progress: number;
+};
+
+declare type WorkflowIdentifiers = {
+  workflowUid: string;
+  workflowName: string;
+};
+
+export {};