clean up

gridaco · Dec 17, 2023 · deb3355 · deb3355
1 parent 8dcded6
commit deb3355
Show file tree

Hide file tree

Showing 10 changed files with 182 additions and 242 deletions.
diff --git a/README.md b/README.md
@@ -156,12 +156,13 @@ We support importing designs from Figma with our [figma-sdk](https://github.com/
 
 ## Usage
 
-Linting
-Custom Tokenizer
-Custom Assets Repository
-Custom Cache
-Custom Cursor
-Plugins
+- [REST API](./www/README.md)
+- Linting (coming soon)
+- Custom Tokenizer (coming soon)
+- Custom Assets Repository (coming soon)
+- Custom Cache (coming soon)
+- Custom Cursor (coming soon)
+- Plugins (coming soon)
 
 ### Running locally
 

diff --git a/api/README.md b/api/README.md
diff --git a/api/__test__/.gitignore b/api/__test__/.gitignore
diff --git a/api/index.ts b/api/index.ts
diff --git a/api/package.json b/api/package.json
diff --git a/www/README.md b/www/README.md
@@ -1,36 +1,166 @@
-This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
+# Grida Code API (Beta) - `code.api.grida.co`
 
-## Getting Started
+## Usage (REST)
 
-First, run the development server:
+### `POST /v1/code`
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+Example
+
+```ts
+import Axios from "axios";
+
+const client = Axios.create({
+  baseURL: "https://code.api.grida.co/v1",
+  headers: {
+    "Content-Type": "application/json",
+    "X-Figma-Access-Token": "figd_xxxxxxxxxx",
+  },
+});
+
+client.post("code", {
+  // target node url formatted as https://www.figma.com/file/{fileKey}?node-id={nodeId}
+  // at this moment, the nodeId must be formatted as 00:00, not 00-00
+  // Note: if you copy & paste the link from the fihma editor, you will get in the format of 00-00 (we are updating this)
+  figma: "https://www.figma.com/file/MikewnarPfXXXXX/?node-id=0%3A1",
+  framework: {
+    framework: "vanilla", // react, flutter, ...
+  },
+});
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+#### Request Body
+
+```ts
+interface CodeRequest {
+  figma: FigmaNodeInput;
+  framework: Partial<FrameworkConfig>;
+}
+```
+
+**`body.figma`**
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+```ts
+type FigmaNodeInput =
+  | string
+  | { url: string; version: string }
+  | { filekey: string; node: string; version: string };
+```
+
+**Note** currently only `string` is supported.
+
+An URL indicating the target node in Figma design.
+
+target node url formatted as `https://www.figma.com/file/{fileKey}?node-id={nodeId}`
+at this moment, the nodeId must be formatted as `00:00`, not `00-00` url encoded value like `0%3A1` is also acceptable.
+
+Note: if you copy & paste the link from the fihma editor, you will get in the format of 00-00 (we are updating this)
 
-This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
+**`body.framework`**
 
-## Learn More
+A Framework configuration used for generating code. Learn more at [Framework Configuration](https://grida.co/docs/cli#2-framework-configuration)
 
-To learn more about Next.js, take a look at the following resources:
+#### Response
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+```ts
+// example of response
+{
+  warnings: [],
+  src: '', // do not use this
+  srcdoc: '<DOCTYPE html><head>...</head><body>...',
+  srcmap: {
+    // the mapping between the generated code and the design
+    // node-id : xpath
+    '123:123': '//div[@data-figma-node-id="123:123"]]'
+  },
+  files:{
+    'index.hml': '<DOCTYPE html><head>...</head><body>...'
+  }
+  framework:{
+    // the framework config used for generating code
+    // ...
+  },
+  // (if the input design source is figma, you will get the brief summary about the used design)
+  figma:{
+    file:{
+      // #region original data ------
+      name: "Exmaples",
+      lastModified: "2023-03-28T17:51:08Z",
+      thumbnailUrl: "https://s3-alpha.figma.com/thumbnails/dc85b86a-2502-4baa-a776-ce0972131a80",
+      version: "3247308401",
+      // #endregion original data ------
+    }
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+    filekey: 'MikewnarPfXXXXX',
+    entry: '0:1',
+    json: "{}",
+    node: {
+      ...
+    }
+  }
+  engine: {
+    // the info of the engine used for generating code
+    name: 'code.api.grida.co/v1',
+    // the engibe version
+    version: '2023.1.1'
+  },
+  // the preview image of the rendered html
+  thumbnail: 'https://xxx.s3.amazonaws.com/.../xxxxxx.png',
+  license: {
+    // the license info of the generated code and the api
+    // ...
+  }
+}
+```
+
+- `warnings` - An array of warnings. If there is no warning, it will be an empty array. (This is usually a warning caused by poor design, which can be ignored)
+- `src` - The generated code as a uri, a publicly accessible html file endpoint.
+- `srcdoc` - The generated code as a bundled and concatenated string, which can be used to embed the code directly into your website.
+
+### `GET /v1/embed`
 
-## Deploy on Vercel
+We also provide an experimental embed API for embedding the generated code directly into your website with an iframe.
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+Example
+
+```html
+<iframe
+  src="https://code.api.grida.co/v1/embed?figma=<figma-node-url>&fpat=figd_xxxxx"
+  width="100%"
+  height="100%"
+></iframe>
+```
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+#### URL Parameters
+
+**`figma`**
+Same as `/v1/code` API's `figma` parameter.
+
+**`fpat`** or **`fat`**
+
+- fpat: Figma Personal Access Token (starting with `figd_`)
+- fat: Figma Access Token
+
+Warning: For security reasons, we highly recommend using the Figma Access Token (which expires), instead of the Figma Personal Access Token (which never expires unless revoked). The Figma Personal Access Token is only used for development purpose.
+
+We are planning on providing a more secure way to use embed with the `fpat` in the future.
+
+The framework configuration for embed is `vanilla-preview` by default. We are planning on providing a way to customize the framework configuration in the future.
+
+## Request / Response Types Declarations
+
+See [./types.ts](./types.ts)
+
+## API Clients (Under Development)
+
+At this moment there is no publicly available API wrappers. If you are looking for use on your local machine, you van use [Grida CLI](https://grida.co/cli)
+
+## Running Locally
+
+First, run the development server:
+
+```bash
+yarn
+yarn dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
diff --git a/www/app/v1/code/route.ts b/www/app/v1/code/route.ts
@@ -1,6 +1,6 @@
 import { code } from "@grida/code";
-import type { CodeRequest, FigmaToVanillaResponse } from "@grida/api/types";
-import { LICENSE_CE } from "@grida/api";
+import { LICENSE_CE } from "@/license";
+import type { CodeRequest, FigmaToVanillaResponse } from "@/types";
 import assert from "assert";
 import { FrameworkConfig, VanillaFrameworkConfig } from "@grida/builder-config";
 import { type NextRequest, NextResponse } from "next/server";

diff --git a/api/license.ts → www/license.ts b/api/license.ts → www/license.ts
diff --git a/api/types.ts → www/types.ts b/api/types.ts → www/types.ts